@lion/ui 0.8.5 → 0.8.6

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

@@ -1,68 +0,0 @@
-# Node Tools >> Providence Analytics >> Local configuration ||40
-
-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
-
-### Category info
-
-Based on the filePath of a result, a category can be added.
-For example:
-
-```js
-export default {
-  metaConfig: {
-    categoryConfig: [
-      {
-        // This is the name found in package.json
-        project: '@lion/ui/root.js',
-        // These conditions will be run on overy filePath
-        categories: {
-          core: p => p.startsWith('./packages/core'),
-          utils: p => p.startsWith('./packages/ajax') || p.startsWith('./packages/localize'),
-          overlays: p =>
-            p.startsWith('./packages/overlays') ||
-            p.startsWith('./packages/dialog') ||
-            p.startsWith('./packages/tooltip'),
-          ...
-        },
-      },
-    ],
-  },
-}
-```
-
-> N.B. category info is regarded as subjective, therefore it's advised to move this away from
-> Analyzers (and thus file-system cache). Categories can be added realtime in the dashboard.
-
-## Project paths
-
-### referenceCollections
-
-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](https://github.com/ing-bank/lion/blob/8dc51c1066421b9b482f2d9964afcbfa9ce2f730/docs/fundamentals/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/ui/form.js']
-
-An example:
-
-```js
-  referenceCollections: {
-    // Our products
-    'lion-based-ui': [
-      './providence-input-data/references/lion-based-ui',
-      './providence-input-data/references/lion-based-ui-labs',
-    ],
-    ...
-  }
-```
-
-### searchTargetCollections
-
-A list of file system paths. They can be defined relative from the current project root
-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).

package/docs/fundamentals/node-tools/providence-analytics/QueryResult.md

@@ -1,111 +0,0 @@
-# Node Tools >> Providence Analytics >> QueryResult ||50
-
-When an Analyzer has run, it returns a QueryResult. This is a json object that contains all
-meta info (mainly configuration parameters) and the query output.
-A QueryResult always contains the analysis of one project (a target project). Optionally,
-it can contain a reference project as well.
-
-## Anatomy
-
-A QueryResult starts with a meta section, followed by the actual results
-
-### Meta
-
-The meta section lists all configuration options the analyzer was run with. Here, you see an
-example of a `find-imports` QueryResult:
-
-```js
-  "meta": {
-    "searchType": "ast-analyzer",
-    "analyzerMeta": {
-      "name": "find-imports",
-      "requiredAst": "babel",
-      "identifier": "importing-target-project_0.0.2-target-mock__1970011674",
-      "targetProject": {
-        "name": "importing-target-project",
-        "commitHash": "3e5014d6ecdff1fc71138cdb29aaf7bf367588f5",
-        "version": "0.0.2-target-mock"
-      },
-      "configuration": {
-        "keepInternalSources": false
-      }
-    }
-  },
-```
-
-### Output
-
-The output is usually more specifically tied to the Analyzer. What most regular Analyzers
-(not being MatchAnalyzers that require a referenceProjectPath) have in common, is that their
-results are being shown per "entry" (an entry corresponds with an AST generated by Babel, which in
-turn corresponds to a file found in a target or reference project).
-
-Below an example is shown of `find-imports` QueryOutput:
-
-```js
-  "queryOutput": [
-    {
-      "project": {
-        "name": "importing-target-project",
-        "mainEntry": "./target-src/match-imports/root-level-imports.js",
-        "version": "0.0.2-target-mock",
-        "commitHash": "3e5014d6ecdff1fc71138cdb29aaf7bf367588f5"
-      },
-      "entries": [
-        {
-          "file": "./target-src/find-imports/all-notations.js",
-          "result": [
-            {
-              "importSpecifiers": [
-                "[file]"
-              ],
-              "source": "imported/source",
-              "normalizedSource": "imported/source",
-              "fullSource": "imported/source"
-            },
-            {
-              "importSpecifiers": [
-                "[default]"
-              ],
-              "source": "imported/source-a",
-              "normalizedSource": "imported/source-a",
-              "fullSource": "imported/source-a"
-            },
-            ...
-```
-
-MatchAnalyzers usually do post processing on the entries. The output below (for the `match-imports`
-Analyzer) shows an ordering by matched specifier.
-
-```js
- "queryOutput": [
-    {
-      "exportSpecifier": {
-        "name": "[default]",
-        "project": "exporting-ref-project",
-        "filePath": "./index.js",
-        "id": "[default]::./index.js::exporting-ref-project"
-      },
-      "matchesPerProject": [
-        {
-          "project": "importing-target-project",
-          "files": [
-            "./target-src/match-imports/root-level-imports.js",
-            "./target-src/match-subclasses/internalProxy.js"
-          ]
-        }
-      ]
-    },
-    ...
-```
-
-Due to some legacy decisions, the QueryOutput allows for multiple target- and reference projects.
-Aggregation of data now takes place in the dashboard.
-QueryOutputs always contain one or a combination of two projects. This means that the
-QueryOutput structure could be simplified in the future.
-
-## Environment agnosticism
-
-The output files stored in the file system always need to be machine independent:
-this means that all machine specific information, like a complete filepath, needs to be removed from a QueryOutput (paths relative from project root are still allowed).
-In that way, the caching mechanism (based on hash comparisons) as described in [Analyzer](https://github.com/ing-bank/lion/blob/8dc51c1066421b9b482f2d9964afcbfa9ce2f730/docs/fundamentals/node-tools/providence-analytics/analyzer.md) is guaranteed to work across different machines.

package/docs/fundamentals/node-tools/providence-analytics/analyzer.md

@@ -1,69 +0,0 @@
-# Node Tools >> Providence Analytics >> Analyzer ||20
-
-Analyzers form the core of Providence. They contain predefined queries based on AST traversal/analysis.
-A few examples are:
-
-- find-imports
-- find-exports
-- match-imports
-
-An analyzer will give back a [QueryResult](https://github.com/ing-bank/lion/blob/8dc51c1066421b9b482f2d9964afcbfa9ce2f730/docs/fundamentals/node-tools/providence-analytics/QueryResult.md) that will be written to the file system by Providence.
-All analyzers need to extend from the `Analyzer` base class, found in `src/program/analyzers/helpers`.
-
-## Public api
-
-Providence has the following configuration api:
-
-- name (string)
-- requiresReference (boolean)
-  An analyzer will always need a targetProjectPath and can optionally have a referenceProjectPath.
-  In the latter case, it needs to have `requiresReference: true` configured.
-
-During AST traversal, the following api can be consulted
-
-- `.targetData`
-- `.referenceData`
-- `.identifier`
-
-## Phases
-
-### Prepare phase
-
-In this phase, all preparations will be done to run the analysis. Providence is designed to be performant and therefore will first look if it finds an already existing, cached result for the current setup.
-
-### Traverse phase
-
-The ASTs are created for all projects involved and the data are extracted into a QueryOutput. This output can optionally be post processed.
-
-### Finalize phase
-
-The data are normalized and written to the filesystem in JSON format.
-
-## Targets and references
-
-Every Analyzer needs a targetProjectPath. A targetProjectPath is a file path String that.
-
-## Types
-
-We can roughly distinguish two types of analyzers: those that require a reference and those that don't require a reference.
-
-## Database
-
-In order to share data across multiple machines, results are written to the filesystem in a
-"machine agnostic" way. They can be shared through git and serve as a local database.
-
-### Caching
-
-In order to make caching possible, Providence creates an "identifier": a hash from the combination of project versions + Analyzer configuration. When an identifier already exists in the filesystem, the result can be read from cache. This increases performance and helps mitigate memory problems that can occur when handling large amounts of data in a batch.
-
-## Analyzer helpers
-
-Inside the folder './src/program/analyzers', a folder 'helpers' is found.
-Helpers are created specifically for use within analyzers and have knowledge about
-the context of the analyzer (knowledge about an AST and/or QueryResult structure).
-
-Generic functionality (that can be applied in any context) can be found in './src/program/utils'.
-
-## Post processors
-
-Post processors are imported by analyzers and act on their outputs. They can be enabled via the configuration of an analyzer. They can be found in './src/program/analyzers/post-processors'. For instance: transform the output of analyzer 'find-imports' by sorting on specifier instead of the default (entry). Other than most configurations of analyzers, post processors act on the total result of all analyzed files instead of just one file/ ast entry.