[ADF-3809] Added file checker tool and updated doc files (#4052)

* [ADF-3809] Added file checker tool

* [ADF-3809] Updated doc files based on file checker report

tools/doc/doctool.config.json

@@ -21,7 +21,7 @@
             "toc"
         ],
         "dev": [
-            "sourceLinker"
+            "fileChecker"
         ]
     },
     "statusIcons": {
@@ -141,5 +141,12 @@
         "external-alfresco",
         "content-node-share",
         "tree-view"
+    ],
+    "fileCheckerFilter": [
+        "README",
+        "release-notes",
+        "tutorials",
+        "user-guide",
+        "versionIndex"
     ]
 }

tools/doc/tools/fileChecker.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var path = require("path");
+var fs = require("fs");
+var unist_util_select_1 = require("unist-util-select");
+var ngHelpers = require("../ngHelpers");
+//const angFilenameRegex = /([a-zA-Z0-9\-]+)\.((component)|(directive)|(interface)|(model)|(pipe)|(service)|(widget))/;
+var imageFolderPath = path.resolve('docs', 'docassets', 'images');
+function processDocs(mdCache, aggData, errorMessages) {
+    var pathnames = Object.keys(mdCache);
+    var classlessDocs = [];
+    var linkRefs = {};
+    var imageRefs = {};
+    var filters = makeFilepathFilters(aggData.config["fileCheckerFilter"]);
+    pathnames.forEach(function (pathname) {
+        var fileBaseName = path.basename(pathname, '.md');
+        var tree = mdCache[pathname].mdOutTree;
+        var className = ngHelpers.ngNameToClassName(fileBaseName, aggData.config.typeNameExceptions);
+        var classInfo = aggData.classInfo[className];
+        if (!classInfo) {
+            if (!filterFilepath(filters, pathname)) {
+                classlessDocs.push(pathname);
+            }
+        }
+        else {
+            var linkElems = unist_util_select_1.selectAll('link', tree);
+            linkElems.forEach(function (linkElem) {
+                var normUrl = normaliseLinkPath(pathname, linkElem.url);
+                if (linkRefs[normUrl]) {
+                    linkRefs[normUrl].push(pathname);
+                }
+                else {
+                    linkRefs[normUrl] = [pathname];
+                }
+            });
+        }
+        var imageElems = unist_util_select_1.selectAll('image', tree);
+        imageElems.forEach(function (imageElem) {
+            var normUrl = normaliseLinkPath(pathname, imageElem.url);
+            if (imageRefs[normUrl]) {
+                imageRefs[normUrl].push(pathname);
+            }
+            else {
+                imageRefs[normUrl] = [pathname];
+            }
+        });
+    });
+    classlessDocs.forEach(function (docPath) {
+        var relDocPath = docPath.substring(docPath.indexOf('docs'));
+        console.group("Warning: no source class found for \"" + relDocPath + "\"");
+        if (linkRefs[docPath]) {
+            linkRefs[docPath].forEach(function (linkRef) {
+                var relLinkPath = linkRef.substring(linkRef.indexOf('docs'));
+                console.log("Linked from: \"" + relLinkPath + "\"");
+            });
+        }
+        console.groupEnd();
+    });
+    var imagePaths = getImagePaths(imageFolderPath);
+    imagePaths.forEach(function (imagePath) {
+        if (!imageRefs[imagePath]) {
+            var relImagePath = imagePath.substring(imagePath.indexOf('docs'));
+            console.log("Warning: no links to image file \"" + relImagePath + "\"");
+        }
+    });
+}
+exports.processDocs = processDocs;
+function normaliseLinkPath(homeFilePath, linkUrl) {
+    var homeFolder = path.dirname(homeFilePath);
+    return path.resolve(homeFolder, linkUrl);
+}
+function getImagePaths(imageFolder) {
+    var files = fs.readdirSync(imageFolder);
+    return files.map(function (f) { return path.resolve(imageFolder, f); });
+}
+function makeFilepathFilters(regexes) {
+    return regexes.map(function (r) { return new RegExp(r); });
+}
+function filterFilepath(filters, filepath) {
+    for (var i = 0; i < filters.length; i++) {
+        if (filters[i].test(filepath)) {
+            return true;
+        }
+    }
+    return false;
+}

tools/doc/tools/fileChecker.ts

@@ -0,0 +1,109 @@
+import * as path from "path";
+import * as fs from "fs";
+
+import { select, selectAll } from "unist-util-select";
+
+import * as ngHelpers from "../ngHelpers";
+
+
+//const angFilenameRegex = /([a-zA-Z0-9\-]+)\.((component)|(directive)|(interface)|(model)|(pipe)|(service)|(widget))/;
+const imageFolderPath = path.resolve('docs', 'docassets', 'images');
+
+
+export function processDocs(mdCache, aggData, errorMessages) {
+    var pathnames = Object.keys(mdCache);
+
+    let classlessDocs = [];
+    let linkRefs = {};
+    let imageRefs = {};
+
+    let filters = makeFilepathFilters(aggData.config["fileCheckerFilter"]);
+
+    pathnames.forEach(pathname => {
+
+        let fileBaseName = path.basename(pathname, '.md');
+        let tree = mdCache[pathname].mdOutTree;
+        let className = ngHelpers.ngNameToClassName(fileBaseName, aggData.config.typeNameExceptions);
+        let classInfo = aggData.classInfo[className];
+
+        if (!classInfo) {
+            if (!filterFilepath(filters, pathname)) {
+                classlessDocs.push(pathname);
+            }
+        } else {
+            let linkElems = selectAll('link', tree);
+            
+            linkElems.forEach(linkElem => {
+                let normUrl = normaliseLinkPath(pathname, linkElem.url);
+
+                if (linkRefs[normUrl]) {
+                    linkRefs[normUrl].push(pathname);
+                } else {
+                    linkRefs[normUrl] = [ pathname ];
+                }
+            });
+        }
+
+        let imageElems = selectAll('image', tree);
+
+        imageElems.forEach(imageElem => {
+            let normUrl = normaliseLinkPath(pathname, imageElem.url);
+
+            if (imageRefs[normUrl]) {
+                imageRefs[normUrl].push(pathname);
+            } else {
+                imageRefs[normUrl] = [ pathname ];
+            }
+        });
+    });
+
+    classlessDocs.forEach(docPath => {
+        let relDocPath = docPath.substring(docPath.indexOf('docs'));
+        console.group(`Warning: no source class found for "${relDocPath}"`);
+
+        if (linkRefs[docPath]) {
+            linkRefs[docPath].forEach(linkRef => {
+                let relLinkPath = linkRef.substring(linkRef.indexOf('docs'));
+                console.log(`Linked from: "${relLinkPath}"`);
+            });
+        }
+
+        console.groupEnd();
+    });
+
+    let imagePaths = getImagePaths(imageFolderPath);
+
+    imagePaths.forEach(imagePath => {
+        if (!imageRefs[imagePath]) {
+            let relImagePath = imagePath.substring(imagePath.indexOf('docs'));
+            console.log(`Warning: no links to image file "${relImagePath}"`);
+        }
+    });
+}
+
+
+function normaliseLinkPath(homeFilePath, linkUrl) {
+    let homeFolder = path.dirname(homeFilePath);
+    return path.resolve(homeFolder, linkUrl);
+}
+
+
+function getImagePaths(imageFolder) {
+    let files = fs.readdirSync(imageFolder);
+    return files.map(f => path.resolve(imageFolder, f));
+}
+
+
+function makeFilepathFilters(regexes: string[]) {
+    return regexes.map(r => new RegExp(r));
+}
+
+
+function filterFilepath(filters: RegExp[], filepath: string): boolean {
+    for (let i = 0; i < filters.length; i++) {
+        if (filters[i].test(filepath)) {
+            return true
+        }
+    }
+    return false;
+}