chore(providence): expose types; improve logging and formatting

.changeset/witty-seals-love.md

@@ -0,0 +1,8 @@
+---
+'providence-analytics': patch
+---
+
+- expose types; improve logging and formatting
+- apply memoisation in optimised-glob
+- add perf logs to LogService
+- allow to clear cache of memoized function

packages-node/providence-analytics/package.json

@@ -24,7 +24,8 @@
   },
   "files": [
     "inlined-swc-to-babel",
-    "src"
+    "src",
+    "types"
   ],
   "scripts": {
     "dashboard": "node ./src/dashboard/server.js --run-server --serve-from-package-root",

packages-node/providence-analytics/src/program/analyzers/find-classes.js

@@ -1,10 +1,11 @@
 /* eslint-disable no-shadow, no-param-reassign */
 import path from 'path';
 
-import t from '@babel/types';
 import babelTraverse from '@babel/traverse';
-import { Analyzer } from '../core/Analyzer.js';
+import t from '@babel/types';
+
 import { trackDownIdentifierFromScope } from '../utils/track-down-identifier--legacy.js';
+import { Analyzer } from '../core/Analyzer.js';
 
 /**
  * @typedef {import('@babel/types').File} File

packages-node/providence-analytics/src/program/analyzers/match-imports.js

@@ -1,5 +1,5 @@
 /* eslint-disable no-continue */
-import pathLib from 'path';
+import path from 'path';
 /* eslint-disable no-shadow, no-param-reassign */
 import FindImportsAnalyzer from './find-imports.js';
 import FindExportsAnalyzer from './find-exports.js';
@@ -9,14 +9,15 @@ import { transformIntoIterableFindExportsOutput } from './helpers/transform-into
 import { transformIntoIterableFindImportsOutput } from './helpers/transform-into-iterable-find-imports-output.js';
 
 /**
- * @typedef {import('../../../types/index.js').FindImportsAnalyzerResult} FindImportsAnalyzerResult
- * @typedef {import('../../../types/index.js').FindExportsAnalyzerResult} FindExportsAnalyzerResult
+ * @typedef {import('../../../types/index.js').ConciseMatchImportsAnalyzerResult} ConciseMatchImportsAnalyzerResult
  * @typedef {import('../../../types/index.js').IterableFindExportsAnalyzerEntry} IterableFindExportsAnalyzerEntry
  * @typedef {import('../../../types/index.js').IterableFindImportsAnalyzerEntry} IterableFindImportsAnalyzerEntry
- * @typedef {import('../../../types/index.js').ConciseMatchImportsAnalyzerResult} ConciseMatchImportsAnalyzerResult
- * @typedef {import('../../../types/index.js').MatchImportsConfig} MatchImportsConfig
- * @typedef {import('../../../types/index.js').MatchImportsAnalyzerResult} MatchImportsAnalyzerResult
  * @typedef {import('../../../types/index.js').PathRelativeFromProjectRoot} PathRelativeFromProjectRoot
+ * @typedef {import('../../../types/index.js').MatchImportsAnalyzerResult} MatchImportsAnalyzerResult
+ * @typedef {import('../../../types/index.js').FindImportsAnalyzerResult} FindImportsAnalyzerResult
+ * @typedef {import('../../../types/index.js').FindExportsAnalyzerResult} FindExportsAnalyzerResult
+ * @typedef {import('../../../types/index.js').AnalyzerQueryResult} AnalyzerQueryResult
+ * @typedef {import('../../../types/index.js').MatchImportsConfig} MatchImportsConfig
  * @typedef {import('../../../types/index.js').PathFromSystemRoot} PathFromSystemRoot
  * @typedef {import('../../../types/index.js').AnalyzerName} AnalyzerName
  * @typedef {import('../../../types/index.js').AnalyzerAst} AnalyzerAst
@@ -117,7 +118,7 @@ async function matchImportsPostprocess(exportsAnalyzerResult, importsAnalyzerRes
       const fromImportToExport = await fromImportToExportPerspective({
         importee: importEntry.normalizedSource,
         importer: /** @type {PathFromSystemRoot} */ (
-          pathLib.resolve(importProjectPath, importEntry.file)
+          path.resolve(importProjectPath, importEntry.file)
         ),
         importeeProjectPath: cfg.referenceProjectPath,
       });
@@ -193,6 +194,7 @@ export default class MatchImportsAnalyzer extends Analyzer {
      * Prepare
      */
     const cachedAnalyzerResult = await this._prepare(cfg);
+
     if (cachedAnalyzerResult) {
       return cachedAnalyzerResult;
     }
@@ -205,6 +207,7 @@ export default class MatchImportsAnalyzer extends Analyzer {
         targetProjectPath: cfg.referenceProjectPath,
         skipCheckMatchCompatibility: cfg.skipCheckMatchCompatibility,
         suppressNonCriticalLogs: true,
+        gatherFilesConfig: cfg.gatherFilesConfigReference,
       });
     }
 
@@ -216,6 +219,7 @@ export default class MatchImportsAnalyzer extends Analyzer {
         targetProjectPath: cfg.targetProjectPath,
         skipCheckMatchCompatibility: cfg.skipCheckMatchCompatibility,
         suppressNonCriticalLogs: true,
+        gatherFilesConfig: cfg.gatherFilesConfig,
       });
     }
 

packages-node/providence-analytics/src/program/core/Analyzer.js

@@ -1,27 +1,39 @@
 /* eslint-disable no-param-reassign */
-import semver from 'semver';
 import path from 'path';
-import { LogService } from './LogService.js';
-import { QueryService } from './QueryService.js';
-import { ReportService } from './ReportService.js';
+
+import semver from 'semver';
+
+import { getFilePathRelativeFromRoot } from '../utils/get-file-path-relative-from-root.js';
 import { InputDataService } from './InputDataService.js';
 import { toPosixPath } from '../utils/to-posix-path.js';
-import { getFilePathRelativeFromRoot } from '../utils/get-file-path-relative-from-root.js';
+import { ReportService } from './ReportService.js';
+import { QueryService } from './QueryService.js';
+import { LogService } from './LogService.js';
 
 /**
- * @typedef {import("@swc/core").Module} SwcAstModule
- * @typedef {import('../../../types/index.js').AnalyzerName} AnalyzerName
- * @typedef {import('../../../types/index.js').AnalyzerAst} AnalyzerAst
- * @typedef {import('../../../types/index.js').PathFromSystemRoot} PathFromSystemRoot
- * @typedef {import('../../../types/index.js').QueryOutput} QueryOutput
- * @typedef {import('../../../types/index.js').ProjectInputData} ProjectInputData
+ * @typedef {(ast: File, astContext: {code:string; relativePath:string; projectData: ProjectInputDataWithMeta}) => object} FileAstTraverseFn
  * @typedef {import('../../../types/index.js').ProjectInputDataWithMeta} ProjectInputDataWithMeta
  * @typedef {import('../../../types/index.js').AnalyzerQueryResult} AnalyzerQueryResult
  * @typedef {import('../../../types/index.js').MatchAnalyzerConfig} MatchAnalyzerConfig
+ * @typedef {import('../../../types/index.js').PathFromSystemRoot} PathFromSystemRoot
+ * @typedef {import('../../../types/index.js').ProjectInputData} ProjectInputData
+ * @typedef {import('../../../types/index.js').AnalyzerName} AnalyzerName
+ * @typedef {import('../../../types/index.js').AnalyzerAst} AnalyzerAst
+ * @typedef {import('../../../types/index.js').QueryOutput} QueryOutput
+ * @typedef {import("@swc/core").Module} SwcAstModule
  * @typedef {import('@babel/types').File} File
- * @typedef {(ast: File, astContext: {code:string; relativePath:string; projectData: ProjectInputDataWithMeta}) => object} FileAstTraverseFn
  */
 
+/**
+ * @param {string} identifier
+ */
+function displayProjectsInLog(identifier) {
+  const [target, targetV, , reference, referenceV] = identifier.split('_');
+  return decodeURIComponent(
+    `${target}@${targetV} ${reference ? `- ${reference}@${referenceV}` : ''}`,
+  );
+}
+
 /**
  * Analyzes one entry: the callback can traverse a given ast for each entry
  * @param {ProjectInputDataWithMeta} projectData
@@ -247,12 +259,7 @@ export class Analyzer {
       if (!compatible) {
         if (!cfg.suppressNonCriticalLogs) {
           LogService.info(
-            `skipping ${LogService.pad(this.name, 16)} for ${
-              this.identifier
-            }: (${reason})\n${cfg.targetProjectPath.replace(
-              `${process.cwd()}/providence-input-data/search-targets/`,
-              '',
-            )}`,
+            `${LogService.pad(`skipping  ${this.name} (${reason})`)}${displayProjectsInLog(this.identifier)}`,
           );
         }
         return ensureAnalyzerResultFormat(`[${reason}]`, cfg, this);
@@ -273,24 +280,43 @@ export class Analyzer {
     }
 
     if (!cfg.suppressNonCriticalLogs) {
-      LogService.info(`starting ${LogService.pad(this.name, 16)} for ${this.identifier}`);
+      LogService.info(
+        `${LogService.pad(`starting ${this.name}`)}${displayProjectsInLog(this.identifier)}`,
+      );
     }
 
     /**
      * Get reference and search-target data
      */
     if (!cfg.targetProjectResult) {
+      performance.mark('analyzer--prepare--createDTarg-start');
       this.targetData = await InputDataService.createDataObject(
         [cfg.targetProjectPath],
         cfg.gatherFilesConfig,
       );
+      performance.mark('analyzer--prepare--createDTarg-end');
+      const m1 = performance.measure(
+        'analyzer--prepare--createDTarg',
+        'analyzer--prepare--createDTarg-start',
+        'analyzer--prepare--createDTarg-end',
+      );
+      LogService.perf(m1);
     }
 
     if (cfg.referenceProjectPath) {
+      performance.mark('analyzer--prepare--createDRef-start');
+
       this.referenceData = await InputDataService.createDataObject(
         [cfg.referenceProjectPath],
         cfg.gatherFilesConfigReference || cfg.gatherFilesConfig,
       );
+      performance.mark('analyzer--prepare--createDRef-end');
+      const m2 = performance.measure(
+        'analyzer--prepare--createDRef',
+        'analyzer--prepare--createDRef-start',
+        'analyzer--prepare--createDRef-end',
+      );
+      LogService.perf(m2);
     }
 
     return undefined;
@@ -304,10 +330,21 @@ export class Analyzer {
   _finalize(queryOutput, cfg) {
     LogService.debug(`Analyzer "${this.name}": started _finalize method`);
 
+    performance.mark('analyzer--finalize-start');
     const analyzerResult = ensureAnalyzerResultFormat(queryOutput, cfg, this);
     if (!cfg.suppressNonCriticalLogs) {
-      LogService.success(`finished ${LogService.pad(this.name, 16)} for ${this.identifier}`);
+      LogService.success(
+        `${LogService.pad(`finished ${this.name}`)}${displayProjectsInLog(this.identifier)}`,
+      );
     }
+    performance.mark('analyzer--finalize-end');
+    const measurementFinalize = performance.measure(
+      'analyzer--finalize',
+      'analyzer--finalize-start',
+      'analyzer--finalize-end',
+    );
+    LogService.perf(measurementFinalize);
+
     return analyzerResult;
   }
 

packages-node/providence-analytics/src/program/providence.js

@@ -9,13 +9,13 @@ import { LogService } from './core/LogService.js';
 import { AstService } from './core/AstService.js';
 
 /**
- * @typedef {import('../../types/index.js').ProvidenceConfig} ProvidenceConfig
- * @typedef {import('../../types/index.js').PathFromSystemRoot} PathFromSystemRoot
- * @typedef {import('../../types/index.js').QueryResult} QueryResult
  * @typedef {import('../../types/index.js').AnalyzerQueryResult} AnalyzerQueryResult
- * @typedef {import('../../types/index.js').QueryConfig} QueryConfig
  * @typedef {import('../../types/index.js').AnalyzerQueryConfig} AnalyzerQueryConfig
+ * @typedef {import('../../types/index.js').PathFromSystemRoot} PathFromSystemRoot
  * @typedef {import('../../types/index.js').GatherFilesConfig} GatherFilesConfig
+ * @typedef {import('../../types/index.js').ProvidenceConfig} ProvidenceConfig
+ * @typedef {import('../../types/index.js').QueryResult} QueryResult
+ * @typedef {import('../../types/index.js').QueryConfig} QueryConfig
  */
 
 /**
@@ -81,6 +81,8 @@ function getSlicedQueryConfig(queryConfig, targetProjectPath, referenceProjectPa
  * @param {{ gatherFilesConfig:GatherFilesConfig, gatherFilesConfigReference:GatherFilesConfig, skipCheckMatchCompatibility:boolean }} cfg
  */
 async function handleAnalyzerForProjectCombo(slicedQConfig, cfg) {
+  performance.mark(`${slicedQConfig.analyzerName}-start`);
+
   const queryResult = await QueryService.astSearch(slicedQConfig, {
     gatherFilesConfig: cfg.gatherFilesConfig,
     gatherFilesConfigReference: cfg.gatherFilesConfigReference,
@@ -88,6 +90,17 @@ async function handleAnalyzerForProjectCombo(slicedQConfig, cfg) {
     addSystemPathsInResult: cfg.addSystemPathsInResult,
     ...slicedQConfig.analyzerConfig,
   });
+
+  performance.mark(`${slicedQConfig.analyzerName}-end`);
+  const measurement = /** @type {* & PerformanceMeasure} */ (
+    performance.measure(
+      slicedQConfig.analyzerName,
+      `${slicedQConfig.analyzerName}-start`,
+      `${slicedQConfig.analyzerName}-end`,
+    )
+  );
+  LogService.perf(measurement);
+
   if (queryResult) {
     report(queryResult, cfg);
   }

packages-node/providence-analytics/test-node/program/utils/memoize.test.js

@@ -335,11 +335,11 @@ describe('Memoize', () => {
 
       // Now the original function is called again
       expect(sumMemoized('1', '2')).to.equal('12');
-      expect(sumCalled).to.equal(3);
+      expect(sumCalled).to.equal(2);
 
       // Return from new cache again
       expect(sumMemoized('1', '2')).to.equal('12');
-      expect(sumCalled).to.equal(3);
+      expect(sumCalled).to.equal(2);
     });
   });
 });