feat(providence): improve dashboard

Author: tlouisse

.changeset/giant-ears-try.md

@@ -0,0 +1,12 @@
+---
+'providence-analytics': minor
+---
+
+Improved dashboard:
+
+- allows to configure categories in `providence.conf.(m)js`that show up in dashboard
+- exposes dashboard in cli: `npx providence dashboard`
+
+BREAKING CHANGES:
+
+- `providence.conf.(m)js` must be in ESM format.

.editorconfig

@@ -12,7 +12,7 @@ trim_trailing_whitespace = true
 indent_size = unset
 trim_trailing_whitespace = false
 
-[*.{html,js,md,mdx}]
+[*.{html,js,mjs,md,mdx}]
 block_comment_start = /**
 block_comment = *
 block_comment_end = */
@@ -23,4 +23,4 @@ indent_style = unset
 indent_size = unset
 end_of_line = unset
 insert_final_newline = unset
-trim_trailing_whitespace = unset
+trim_trailing_whitespace = unset

docs/docs/node-tools/providence-analytics/LocalConfiguration.md

@@ -1,7 +1,11 @@
 # Node Tools >> Providence Analytics >> Local configuration ||40
 
-The file `providence.conf.js` is read by providence cli and by the dashboard to get all
-default configurations.
+The Providence configuration file is read by providence cli (optional) and by the dashboard (required).
+It has a few requirements:
+
+- it must be called `providence.conf.js` or `providence.conf.mjs`
+- it must be in ESM format
+- it must be located in the root of a repository (under `process.cwd()`)
 
 ## Meta data
 
@@ -11,6 +15,7 @@ Based on the filePath of a result, a category can be added.
 For example:
 
 ```js
+export default {
   metaConfig: {
     categoryConfig: [
       {
@@ -29,6 +34,7 @@ For example:
       },
     ],
   },
+}
 ```
 
 > N.B. category info is regarded as subjective, therefore it's advised to move this away from
@@ -38,7 +44,7 @@ For example:
 
 ### referenceCollections
 
-A list of file system paths. They can be defined relative from the current project root (`process.cwd()`) or they can be full paths.
+A list of file system paths. They can be defined relative from the current project root or they can be full paths.
 When a [MatchAnalyzer](../../../docs/node-tools/providence-analytics/analyzer.md) like `match-imports` or `match-subclasses` is used, the default reference(s) can be configured here. For instance: ['/path/to/@lion/form']
 
 An example:
@@ -57,6 +63,6 @@ An example:
 ### searchTargetCollections
 
 A list of file system paths. They can be defined relative from the current project root
-(`process.cwd()`) or they can be full paths.
+or they can be full paths.
 When not defined, the current project will be the search target (this is most common when
 providence is used as a dev dependency).

docs/docs/node-tools/providence-analytics/dashboard.md

@@ -6,19 +6,17 @@ application.
 
 ## Run
 
-Start the dashboard via `npm run dashboard` to automatically open the browser and start the dashboard.
+Start the dashboard via `providence dashboard` to automatically open the browser and start the dashboard.
 
 ## Interface
 
 - Select all reference projects
 - Select all target projects
 
-Press `show table` to see the result based on the updated configuration.
-
 ### Generate csv
 
 When `get csv` is pressed, a `.csv` will be downloaded that can be loaded into Excel.
 
 ## Analyzer support
 
-Currently, only the `match-imports` is supported, more analyzers will be added in the future.
+Currently, `match-imports` and `match-subclasses` are supported, more analyzers will be added in the future.

docs/docs/node-tools/providence-analytics/overview.md

@@ -38,11 +38,11 @@ npm i --save-dev providence-analytics
 
 ```json
 "scripts": {
-  "providence": "providence analyze match-imports -r 'node_modules/@lion/*'",
+  "providence:match-imports": "providence analyze match-imports -r 'node_modules/@lion/*'",
 }
 ```
 
-> The example above illustrates how to run the "match-imports" analyzer for reference project 'lion-based-ui'. Note that it is possible to run other analyzers and configurations supported by providence as well. For a full overview of cli options, run `providence --help`. All supported analyzers will be viewed when running `providence analyze`
+> The example above illustrates how to run the "match-imports" analyzer for reference project 'lion-based-ui'. Note that it is possible to run other analyzers and configurations supported by providence as well. For a full overview of cli options, run `npx providence --help`. All supported analyzers will be viewed when running `npx providence analyze`
 
 You are now ready to use providence in your project. All
 data will be stored in json files in the folder `./providence-output`
@@ -57,20 +57,21 @@ data will be stored in json files in the folder `./providence-output`
 ...
 "scripts": {
     ...
-    "providence:dashboard": "node node_modules/providence/dashboard/src/server.js"
+    "providence:dashboard": "providence dashboard"
 }
 ```
 
 ### Add providence.conf.js
 
 ```js
-const providenceConfig = {
+export default {
   referenceCollections: {
-    'lion-based-ui collection': ['./node_modules/lion-based-ui'],
+    'lion-based-ui-collection': [
+      './node_modules/lion-based-ui/packages/x',
+      './node_modules/lion-based-ui/packages/y',
+    ],
   },
 };
-
-module.exports = providenceConfig;
 ```
 
 Run `npm run providence:dashboard`
@@ -124,16 +125,16 @@ Providence requires a queries as input.
 Queries are defined as objects and can be of two types:
 
 - feature-query
-- analyzer
+- ast-analyzer
 
-A `queryConfig` is required as input to run the `providenceMain` function.
+A `QueryConfig` is required as input to run the `providenceMain` function.
 This object specifies the type of query and contains the relevant meta
 information that will later be outputted in the `QueryResult` (the JSON object that
 the `providenceMain` function returns.)
 
 ## Analyzer Query
 
-Analyzers queries are also created via `queryConfig`s.
+Analyzer queries are also created via `QueryConfig`s.
 
 Analyzers can be described as predefined queries that use AST traversal.
 
@@ -147,12 +148,14 @@ Now you will get a list of all predefined analyzers:
 
 - find-imports
 - find-exports
+- find-classes
 - match-imports
-- find-subclasses
+- match-subclasses
 - etc...
 
 ![Analyzer query](./assets/analyzer-query.gif 'Analyzer query')
 
+<!--
 ## Running providence from its own repo
 
 ### How to add a new search target project
@@ -186,3 +189,4 @@ Please run:
 ```bash
 sh ./rm-submodule.sh <path/to/submodule>
 ```
+-->

packages-node/providence-analytics/dashboard/src/app/p-board.js

@@ -1,3 +1,4 @@
+/* eslint-disable lit-a11y/no-invalid-change-handler */
 /* eslint-disable max-classes-per-file */
 import { LitElement, html, css } from 'lit-element';
 import { tooltip as tooltipStyles } from './styles/tooltip.css.js';
@@ -15,6 +16,31 @@ PTable.decorateStyles(tableDecoration);
 
 customElements.define('p-table', PTable);
 
+/**
+ *
+ * @param {{ project:string, filePath:string, name:string }} specifierRes
+ * @param {{ categoryConfig:object }} metaConfig
+ * @returns {string[]}
+ */
+function getCategoriesForMatchedSpecifier(specifierRes, { metaConfig }) {
+  const resultCats = [];
+
+  if (metaConfig && metaConfig.categoryConfig) {
+    const { project, filePath, name } = specifierRes.exportSpecifier;
+    // First of all, do we have a matching project?
+    // TODO: we should allow different configs for different (major) versions
+    const match = metaConfig.categoryConfig.find(cat => cat.project === project);
+    if (match) {
+      Object.entries(match.categories).forEach(([categoryName, matchFn]) => {
+        if (matchFn(filePath, name)) {
+          resultCats.push(categoryName);
+        }
+      });
+    }
+  }
+  return resultCats;
+}
+
 function checkedValues(checkboxOrNodeList) {
   if (!checkboxOrNodeList.length) {
     return checkboxOrNodeList.checked && checkboxOrNodeList.value;
@@ -148,14 +174,18 @@ class PBoard extends DecorateMixin(LitElement) {
 
   _activeAnalyzerSelectTemplate() {
     return html`
-      <select id="active-analyzer">
+      <select id="active-analyzer" @change="${this._onActiveAnalyzerChanged}">
         ${Object.keys(this.__resultFiles).map(
           analyzerName => html` <option value="${analyzerName}">${analyzerName}</option> `,
         )}
       </select>
     `;
   }
 
+  _onActiveAnalyzerChanged() {
+    this._aggregateResults();
+  }
+
   get _selectionMenuFormNode() {
     return this.shadowRoot.getElementById('selection-menu-form');
   }
@@ -228,7 +258,7 @@ class PBoard extends DecorateMixin(LitElement) {
   async __init() {
     await this.__fetchMenuData();
     await this.__fetchResults();
-    // await this.__fetchProvidenceConf();
+    await this.__fetchProvidenceConf();
     this._enrichMenuData();
   }
 
@@ -258,36 +288,20 @@ class PBoard extends DecorateMixin(LitElement) {
     const activeRepos = [...new Set(checkedValues(repos))];
     const activeAnalyzer = this._activeAnalyzerNode.value;
     const totalQueryOutput = this.__aggregateResultData(activeRefs, activeRepos, activeAnalyzer);
-    // function addCategories(specifierRes, metaConfig) {
-    //   const resultCats = [];
-    //   if (metaConfig.categoryConfig) {
-    //     const { project, filePath, name } = specifierRes.exportSpecifier;
-    //     // First of all, do we have a matching project?
-    //     // TODO: we should allow different configs for different (major) versions
-    //     const match = metaConfig.categoryConfig.find(cat => cat.project === project);
-    //     console.log('match', match);
-    //     if (match) {
-    //       Object.entries(match.categories, ([categoryName, matchFn]) => {
-    //         if (matchFn(filePath, name)) {
-    //           resultCats.push(categoryName);
-    //         }
-    //       });
-    //     }
-    //   }
-    //   console.log('resultCats', resultCats, metaConfig);
-
-    //   return resultCats;
-    // }
 
     // Prepare viewData
     const dataResult = [];
     // When we support more analyzers than match-imports and match-subclasses, make a switch
     // here
+
     totalQueryOutput.forEach((specifierRes, i) => {
       dataResult[i] = {};
       dataResult[i].specifier = specifierRes.exportSpecifier;
       dataResult[i].sourceProject = specifierRes.exportSpecifier.project;
-      // dataResult[i].categories = undefined; // addCategories(specifierRes, this.__providenceConf);
+      dataResult[i].categories = getCategoriesForMatchedSpecifier(
+        specifierRes,
+        this.__providenceConf,
+      );
       dataResult[i].type = specifierRes.exportSpecifier.name === '[file]' ? 'file' : 'specifier';
       dataResult[i].count = specifierRes.matchesPerProject
         .map(mpp => mpp.files)
@@ -299,6 +313,7 @@ class PBoard extends DecorateMixin(LitElement) {
 
   __aggregateResultData(activeRefs, activeRepos, activeAnalyzer) {
     const jsonResultsActiveFilter = [];
+
     activeRefs.forEach(ref => {
       const refSearch = `_${ref.replace('#', '_')}_`;
       activeRepos.forEach(dep => {
@@ -419,13 +434,15 @@ class PBoard extends DecorateMixin(LitElement) {
   }
 
   async __fetchMenuData() {
-    // Derived from providence.conf.js
+    // Derived from providence.conf.js, generated in server.mjs
     this.__initialMenuData = await fetch('/menu-data').then(response => response.json());
   }
 
   async __fetchProvidenceConf() {
-    // Gets an
-    this.__providenceConf = await fetch('/providence.conf.js').then(response => response.json());
+    // Gets the providence conf as defined by the end user in providence-conf.(m)js
+    // @ts-ignore
+    // eslint-disable-next-line import/no-absolute-path
+    this.__providenceConf = (await import('/providence-conf.js')).default;
   }
 
   async __fetchResults() {

packages-node/providence-analytics/dashboard/src/app/server.js

@@ -0,0 +1,9 @@
+// @ts-ignore
+const { LogService } = require('../../src/program/services/LogService.js');
+
+LogService.warn(
+  'Running via "dashboard/src/server.js" is deprecated. Please run "providence dashboard" instead.',
+);
+
+// @ts-ignore
+import('./server.mjs');