Merge branch 'master' into synonyms

# Conflicts:
#	tsdoc-config/src/TSDocConfigFile.ts

Author: rbuckton

common/config/rush/pnpm-lock.yaml

@@ -1,6 +1,23 @@
 {
   "name": "eslint-plugin-tsdoc",
   "entries": [
+    {
+      "version": "0.2.1",
+      "tag": "eslint-plugin-tsdoc_v0.2.1",
+      "date": "Tue, 21 Jan 2020 21:26:36 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Use a cache to avoid repeatedly reloading tsdoc.json during linting"
+          }
+        ],
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@microsoft/tsdoc-config\" from `0.12.16` to `0.13.0`"
+          }
+        ]
+      }
+    },
     {
       "version": "0.2.0",
       "tag": "eslint-plugin-tsdoc_v0.2.0",

eslint-plugin/CHANGELOG.json

@@ -1,6 +1,13 @@
 # Change Log - eslint-plugin-tsdoc
 
-This log was last generated on Tue, 19 Nov 2019 22:01:56 GMT and should not be manually modified.
+This log was last generated on Tue, 21 Jan 2020 21:26:36 GMT and should not be manually modified.
+
+## 0.2.1
+Tue, 21 Jan 2020 21:26:36 GMT
+
+### Patches
+
+- Use a cache to avoid repeatedly reloading tsdoc.json during linting
 
 ## 0.2.0
 Tue, 19 Nov 2019 22:01:56 GMT

eslint-plugin/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-tsdoc",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "An ESLint plugin that validates TypeScript doc comments",
   "keywords": [
     "TypeScript",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@microsoft/tsdoc": "0.12.16",
-    "@microsoft/tsdoc-config": "0.12.16"
+    "@microsoft/tsdoc-config": "0.13.0"
   },
   "devDependencies": {
     "@rushstack/eslint-config": "0.4.0",

eslint-plugin/package.json

@@ -0,0 +1,102 @@
+import { TSDocConfigFile } from '@microsoft/tsdoc-config';
+import * as path from 'path';
+
+import { Debug } from './Debug';
+
+interface ICachedConfig {
+  loadTimeMs: number;
+  lastCheckTimeMs: number;
+  configFile: TSDocConfigFile;
+}
+
+// How often to check for modified input files.  If a file's modification timestamp has changed, then we will
+// evict the cache entry immediately.
+const CACHE_CHECK_INTERVAL_MS: number = 3 * 1000;
+
+// Evict old entries from the cache after this much time, regardless of whether the file was detected as being
+// modified or not.
+const CACHE_EXPIRE_MS: number = 20 * 1000;
+
+// If this many objects accumulate in the cache, then it is cleared to avoid a memory leak.
+const CACHE_MAX_SIZE: number = 100;
+
+export class ConfigCache {
+  // findConfigPathForFolder() result --> loaded tsdoc.json configuration
+  private static _cachedConfigs: Map<string, ICachedConfig> = new Map<string, ICachedConfig>();
+
+  /**
+   * Node.js equivalent of performance.now().
+   */
+  private static _getTimeInMs(): number {
+    const [seconds, nanoseconds] = process.hrtime();
+    return seconds * 1000 + nanoseconds / 1000000;
+  }
+
+  public static getForSourceFile(sourceFilePath: string): TSDocConfigFile {
+    const sourceFileFolder: string = path.dirname(path.resolve(sourceFilePath));
+
+    // First, determine the file to be loaded. If not found, the configFilePath will be an empty string.
+    const configFilePath: string = TSDocConfigFile.findConfigPathForFolder(sourceFileFolder);
+
+    // If configFilePath is an empty string, then we'll use the folder of sourceFilePath as our cache key
+    // (instead of an empty string)
+    const cacheKey: string = configFilePath || (sourceFileFolder + '/');
+    Debug.log(`Cache key: "${cacheKey}"`);
+
+    const nowMs: number = ConfigCache._getTimeInMs();
+
+    let cachedConfig: ICachedConfig | undefined = undefined;
+
+    // Do we have a cached object?
+    cachedConfig = ConfigCache._cachedConfigs.get(cacheKey);
+
+    if (cachedConfig) {
+      Debug.log('Cache hit');
+
+      // Is the cached object still valid?
+      const loadAgeMs: number = nowMs - cachedConfig.loadTimeMs;
+      const lastCheckAgeMs: number = nowMs - cachedConfig.lastCheckTimeMs;
+
+      if (loadAgeMs > CACHE_EXPIRE_MS || loadAgeMs < 0) {
+        Debug.log('Evicting because item is expired');
+        cachedConfig = undefined;
+        ConfigCache._cachedConfigs.delete(cacheKey);
+      } else if (lastCheckAgeMs > CACHE_CHECK_INTERVAL_MS || lastCheckAgeMs < 0) {
+        Debug.log('Checking for modifications');
+        cachedConfig.lastCheckTimeMs = nowMs;
+        if (cachedConfig.configFile.checkForModifiedFiles()) {
+          // Invalidate the cache because it failed to load completely
+          Debug.log('Evicting because item was modified');
+          cachedConfig = undefined;
+          ConfigCache._cachedConfigs.delete(cacheKey);
+        }
+      }
+    }
+
+    // Load the object
+    if (!cachedConfig) {
+      if (ConfigCache._cachedConfigs.size > CACHE_MAX_SIZE) {
+        Debug.log('Clearing cache');
+        ConfigCache._cachedConfigs.clear(); // avoid a memory leak
+      }
+
+      const configFile: TSDocConfigFile = TSDocConfigFile.loadFile(configFilePath);
+
+      if (configFile.fileNotFound) {
+        Debug.log(`File not found: "${configFilePath}"`);
+      } else {
+        Debug.log(`Loaded: "${configFilePath}"`);
+      }
+
+      cachedConfig = {
+        configFile,
+        lastCheckTimeMs: nowMs,
+        loadTimeMs: nowMs
+      };
+
+      ConfigCache._cachedConfigs.set(cacheKey, cachedConfig);
+    }
+
+    return cachedConfig.configFile;
+  }
+}

eslint-plugin/src/ConfigCache.ts

@@ -0,0 +1,9 @@
+
+export class Debug {
+  // To debug the plugin, temporarily uncomment the body of this function
+  public static log(message: string): void {
+    // message = require("process").pid + ": " + message;
+    // console.log(message);
+    // require('fs').writeFileSync('C:\\Git\\log.txt', message + '\r\n', { flag: 'as' });
+  }
+}

eslint-plugin/src/Debug.ts

@@ -1,19 +1,19 @@
-
+import * as eslint from "eslint";
+import * as ESTree from "estree";
 import {
   TSDocParser,
   TextRange,
   TSDocConfiguration,
   ParserContext
 } from "@microsoft/tsdoc";
-import {
-  TSDocConfigFile
-} from '@microsoft/tsdoc-config';
-import * as eslint from "eslint";
-import * as ESTree from "estree";
+import { TSDocConfigFile } from '@microsoft/tsdoc-config';
+
+import { Debug } from './Debug';
+import { ConfigCache } from './ConfigCache';
 
 const tsdocMessageIds: {[x: string]: string} = {};
 
-const defaultTSDocConfiguration: TSDocConfiguration = new TSDocConfiguration()
+const defaultTSDocConfiguration: TSDocConfiguration = new TSDocConfiguration();
 defaultTSDocConfiguration.allTsdocMessageIds.forEach((messageId: string) => {
   tsdocMessageIds[messageId] = `${messageId}: {{unformattedText}}`;
 });
@@ -43,33 +43,44 @@ const plugin: IPlugin = {
         }
       },
       create: (context: eslint.Rule.RuleContext) => {
-        const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
-
         const sourceFilePath: string = context.getFilename();
-        const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(sourceFilePath);
+        Debug.log(`Linting: "${sourceFilePath}"`);
 
-        if (!tsdocConfigFile.fileNotFound) {
-          if (tsdocConfigFile.hasErrors) {
-            context.report({
-              loc: { line: 1, column: 1 },
-              messageId: "error-loading-config-file",
-              data: {
-                details: tsdocConfigFile.getErrorSummary()
-              }
-            });
-          }
+        const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration()
 
-          try {
-            tsdocConfigFile.configureParser(tsdocConfiguration);
-          } catch (e) {
-            context.report({
-              loc: { line: 1, column: 1 },
-              messageId: "error-applying-config",
-              data: {
-                details: e.message
-              }
-            });
+        try {
+          const tsdocConfigFile: TSDocConfigFile = ConfigCache.getForSourceFile(sourceFilePath);
+          if (!tsdocConfigFile.fileNotFound) {
+            if (tsdocConfigFile.hasErrors) {
+              context.report({
+                loc: { line: 1, column: 1 },
+                messageId: "error-loading-config-file",
+                data: {
+                  details: tsdocConfigFile.getErrorSummary()
+                }
+              });
+            }
+
+            try {
+              tsdocConfigFile.configureParser(tsdocConfiguration);
+            } catch (e) {
+              context.report({
+                loc: { line: 1, column: 1 },
+                messageId: "error-applying-config",
+                data: {
+                  details: e.message
+                }
+              });
+            }
           }
+        } catch (e) {
+          context.report({
+            loc: { line: 1, column: 1 },
+            messageId: "error-loading-config-file",
+            data: {
+              details: `Unexpected exception: ${e.message}`
+            }
+          });
         }
 
         const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration);

eslint-plugin/src/index.ts

@@ -1,6 +1,21 @@
 {
   "name": "@microsoft/tsdoc-config",
   "entries": [
+    {
+      "version": "0.13.0",
+      "tag": "@microsoft/tsdoc-config_v0.13.0",
+      "date": "Tue, 21 Jan 2020 21:26:36 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Improve tsdoc.json parser to allow JSON comments"
+          },
+          {
+            "comment": "Add a new API TSDocConfigFile.checkForModifiedFiles() to facilitate caching"
+          }
+        ]
+      }
+    },
     {
       "version": "0.12.16",
       "tag": "@microsoft/tsdoc-config_v0.12.16",

tsdoc-config/CHANGELOG.json

@@ -1,6 +1,14 @@
 # Change Log - @microsoft/tsdoc-config
 
-This log was last generated on Tue, 19 Nov 2019 22:01:56 GMT and should not be manually modified.
+This log was last generated on Tue, 21 Jan 2020 21:26:36 GMT and should not be manually modified.
+
+## 0.13.0
+Tue, 21 Jan 2020 21:26:36 GMT
+
+### Minor changes
+
+- Improve tsdoc.json parser to allow JSON comments
+- Add a new API TSDocConfigFile.checkForModifiedFiles() to facilitate caching
 
 ## 0.12.16
 Tue, 19 Nov 2019 22:01:56 GMT

tsdoc-config/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/tsdoc-config",
-  "version": "0.12.16",
+  "version": "0.13.0",
   "description": "A loader for the tsdoc.json file",
   "keywords": [
     "TypeScript",
@@ -22,11 +22,13 @@
   "dependencies": {
     "@microsoft/tsdoc": "0.12.16",
     "ajv": "~6.10.2",
+    "jju": "~1.4.0",
     "resolve": "~1.12.0"
   },
   "devDependencies": {
     "@rushstack/eslint-config": "0.4.0",
     "@types/jest": "24.0.16",
+    "@types/jju": "1.4.1",
     "@types/resolve": "0.0.8",
     "@types/node": "10.17.5",
     "eslint": "^6.0.0",