feat(extract): adds first sketch to get basic stats from the parsed A…

…ST's (#926)

## Description

- adds basic stats per module, derived from the AST

## Motivation and Context

- will help identify barrels (and enable defining rules on them)
- curiosity

## How Has This Been Tested?

- [x] green ci
- [x] additional automated non-regression tests

## Types of changes

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] Documentation only change
- [ ] Refactor (non-breaking change which fixes an issue without
changing functionality)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)

.dependency-cruiser.json

@@ -390,7 +390,9 @@
  // },
  /* Experimental: the parser to use
  */
- "parser": "tsc", // acorn, swc, tsc
+ "parser": "tsc", // acorn, tsc
+ "experimentalStats": true,
+ "metrics": true,
  "enhancedResolveOptions": {
  "exportsFields": ["exports"],
  "aliasFields": ["browser"],

doc/options-reference.md

@@ -33,6 +33,7 @@
  - [`builtInModules`: influencing what to consider built-in (/ core) modules](#builtinmodules-influencing-what-to-consider-built-in--core-modules)
  - [enhancedResolveOptions](#enhancedresolveoptions)
  - [forceDeriveDependents](#forcederivedependents)
+ - [experimentalStats](#experimentalstats)
  - [parser](#parser)
  - [cache](#cache)
  - [progress](#progress)
@@ -1642,13 +1643,29 @@ Dependency-cruiser will automatically determine whether it needs to derive depen
 However, if you want to force them to be derived, you can switch this variable
 to `true`.
 
+### `experimentalStats`
+
+When set to true dependency-cruiser will emit an `experimentalStats` object
+in the result for each module. This feature is not yet used by any of the
+reporters dependency-cruiser ships with. The feature is also _experimental_
+which means it might disappear or change in the future.
+
 ### `parser`
 
 With this _EXPERIMENTAL_ feature you can specify which parser you want to use
 as the primary parser: the `acorn` one, which handles all things javascript
-(commonjs, es-modules, jsx), or one of two parser that can in addition parse
-typescript; microsoft's `tsc` or the faster and smaller (but slightly less
-feature rich) `swc`.
+(commonjs, es-modules, jsx), or microsoft's `tsc` that can in addition parse
+typescript. At this time it's still possible to pass `swc` here, but that value
+is deprecated and will be removed in a future version.
+
+```javascript
+{
+ // ...
+ options: {
+ parser: "tsc";
+ }
+}
+```
 
 `swc` and `tsc` only work when the compilers (respectively `@swc/core` and
 `typescript`) are installed in the same spot as dependency-cruiser is. They're

src/extract/acorn/extract-stats.mjs

@@ -0,0 +1,6 @@
+export default function extractStats(pAST) {
+ return {
+ topLevelStatementCount: pAST?.body?.length || 0,
+ size: pAST?.end || 0,
+ };
+}

src/extract/acorn/extract.mjs

@@ -3,6 +3,7 @@ import extractES6Deps from "./extract-es6-deps.mjs";
 import extractCommonJSDeps from "./extract-cjs-deps.mjs";
 import extractAMDDeps from "./extract-amd-deps.mjs";
 import parse from "./parse.mjs";
+import extractStats from "./extract-stats.mjs";
 
 export function extract(
  { baseDir, moduleSystems, exoticRequireStrings },
@@ -24,3 +25,8 @@ export function extract(
 
  return lDependencies;
 }
+
+export function getStats({ baseDir }, pFileName, pTranspileOptions) {
+ const lAST = parse.getASTCached(join(baseDir, pFileName), pTranspileOptions);
+ return extractStats(lAST);
+}

src/extract/extract-dependencies.mjs

@@ -36,10 +36,10 @@ function extractWithTsc(pCruiseOptions, pFileName, pTranspileOptions) {
 function determineExtractionFunction(pCruiseOptions, pFileName) {
  let lExtractionFunction = acornExtract;
 
- if (swcShouldUse(pCruiseOptions, pFileName)) {
- lExtractionFunction = swcExtract;
- } else if (tscShouldUse(pCruiseOptions, pFileName)) {
+ if (tscShouldUse(pCruiseOptions, pFileName)) {
  lExtractionFunction = extractWithTsc;
+ } else if (swcShouldUse(pCruiseOptions, pFileName)) {
+ lExtractionFunction = swcExtract;
  }
 
  return lExtractionFunction;

src/extract/extract-stats.mjs

@@ -0,0 +1,48 @@
+import {
+ getStats as tscStats,
+ shouldUse as tscShouldUse,
+} from "./tsc/extract.mjs";
+import { getStats as acornStats } from "./acorn/extract.mjs";
+
+/**
+ * @param {IStrictCruiseOptions} pCruiseOptions
+ * @param {string} pFileName
+ * @returns {(IStrictCruiseOptions, string, any) => import("../../types/cruise-result.mjs").IDependency[]}
+ */
+function determineExtractionFunction(pCruiseOptions, pFileName) {
+ let lExtractionFunction = acornStats;
+
+ if (tscShouldUse(pCruiseOptions, pFileName)) {
+ lExtractionFunction = tscStats;
+ }
+
+ return lExtractionFunction;
+}
+
+/**
+ * Returns some stats for the module in pFileName
+ *
+ * @param {string} pFileName path to the file
+ * @param {import("../../types/dependency-cruiser.js").IStrictCruiseOptions} pCruiseOptions cruise options
+ * @param {import("../../types/dependency-cruiser.js").ITranspileOptions} pTranspileOptions an object with tsconfig ('typescript project') options
+ * ('flattened' so there's no need for file access on any
+ * 'extends' option in there)
+ * @return {import("../../types/dependency-cruiser.js").IDependency[]} an array of dependency objects (see above)
+ */
+export default function extractStats(
+ pFileName,
+ pCruiseOptions,
+ pTranspileOptions,
+) {
+ try {
+ return determineExtractionFunction(pCruiseOptions, pFileName)(
+ pCruiseOptions,
+ pFileName,
+ pTranspileOptions,
+ );
+ } catch (pError) {
+ throw new Error(
+ `Extracting stats ran afoul of...\n\n ${pError.message}\n... in ${pFileName}\n\n`,
+ );
+ }
+}

src/extract/index.mjs

@@ -1,9 +1,10 @@
 import extractDependencies from "./extract-dependencies.mjs";
+import extractStats from "./extract-stats.mjs";
 import gatherInitialSources from "./gather-initial-sources.mjs";
 import clearCaches from "./clear-caches.mjs";
 import { bus } from "#utl/bus.mjs";
 
-/* eslint max-params:0 */
+/* eslint max-params:0 , max-lines-per-function:0*/
 function extractRecursive(
  pFileName,
  pCruiseOptions,
@@ -46,6 +47,15 @@ function extractRecursive(
  [
  {
  source: pFileName,
+ ...(pCruiseOptions.experimentalStats
+ ? {
+ experimentalStats: extractStats(
+ pFileName,
+ pCruiseOptions,
+ pTranspileOptions,
+ ),
+ }
+ : {}),
  dependencies: lDependencies,
  },
  ],

src/extract/tsc/extract-stats.mjs

@@ -0,0 +1,6 @@
+export default function extractStats(pAST) {
+ return {
+ topLevelStatementCount: pAST?.statements?.length || 0,
+ size: pAST?.end || 0,
+ };
+}

src/extract/tsc/extract.mjs

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { isTypeScriptCompatible } from "../helpers.mjs";
 import extractTypeScriptDeps from "./extract-typescript-deps.mjs";
 import parse from "./parse.mjs";
+import extractStats from "./extract-stats.mjs";
 
 export function shouldUse({ tsPreCompilationDeps, parser }, pFileName) {
  return (
@@ -21,3 +22,8 @@ export function extract(
  exoticRequireStrings,
  ).filter(({ moduleSystem }) => moduleSystems.includes(moduleSystem));
 }
+
+export function getStats({ baseDir }, pFileName, pTranspileOptions) {
+ const lAST = parse.getASTCached(join(baseDir, pFileName), pTranspileOptions);
+ return extractStats(lAST);
+}

test/extract/__fixtures__/with-stats/output.json

@@ -0,0 +1,52 @@
+[
+ {
+ "source": "test/extract/__mocks__/with-stats/aap.mjs",
+ "experimentalStats": {
+ "topLevelStatementCount": 1,
+ "size": 36
+ },
+ "dependencies": [
+ {
+ "module": "./noot.mjs",
+ "moduleSystem": "es6",
+ "dynamic": false,
+ "exoticallyRequired": false,
+ "dependencyTypes": ["local", "import"],
+ "resolved": "test/extract/__mocks__/with-stats/noot.mjs",
+ "coreModule": false,
+ "followable": true,
+ "couldNotResolve": false,
+ "matchesDoNotFollow": false
+ }
+ ]
+ },
+ {
+ "source": "test/extract/__mocks__/with-stats/noot.mjs",
+ "experimentalStats": {
+ "topLevelStatementCount": 2,
+ "size": 56
+ },
+ "dependencies": [
+ {
+ "module": "./mies.mjs",
+ "moduleSystem": "es6",
+ "dynamic": false,
+ "exoticallyRequired": false,
+ "dependencyTypes": ["local", "import"],
+ "resolved": "test/extract/__mocks__/with-stats/mies.mjs",
+ "coreModule": false,
+ "followable": true,
+ "couldNotResolve": false,
+ "matchesDoNotFollow": false
+ }
+ ]
+ },
+ {
+ "source": "test/extract/__mocks__/with-stats/mies.mjs",
+ "experimentalStats": {
+ "topLevelStatementCount": 1,
+ "size": 20
+ },
+ "dependencies": []
+ }
+]

test/extract/__mocks__/extract-stats-testfile.mjs

@@ -0,0 +1,37 @@
+import { deepEqual } from "node:assert/strict";
+import extractStats from "#extract/acorn/extract-stats.mjs";
+import { getStats } from "#extract/acorn/extract.mjs";
+
+describe("[U] extract/acorn/extractStats", () => {
+ it("should return stats for a given AST", () => {
+ const lAST = {
+ body: [{ type: "FunctionDeclaration" }, { type: "VariableDeclaration" }],
+ end: 100,
+ };
+ deepEqual(extractStats(lAST), {
+ topLevelStatementCount: 2,
+ size: 100,
+ });
+ });
+
+ it("should return 0 for empty AST", () => {
+ deepEqual(extractStats({}), {
+ topLevelStatementCount: 0,
+ size: 0,
+ });
+ });
+});
+
+describe("[I] extract/acorn/extract - getStats", () => {
+ it("should return stats for a given file containing valid javascript", () => {
+ const lStats = getStats(
+ { baseDir: "./test/extract/acorn" },
+ "extract-stats.spec.mjs",
+ { extension: ".mjs" },
+ );
+ deepEqual(lStats, {
+ topLevelStatementCount: 5,
+ size: 1010,
+ });
+ });
+});

test/extract/__mocks__/with-stats/aap.mjs

@@ -0,0 +1 @@
+import * as noot from "./noot.mjs";

test/extract/__mocks__/with-stats/mies.mjs

@@ -0,0 +1 @@
+export default 456;

test/extract/__mocks__/with-stats/noot.mjs

@@ -0,0 +1,2 @@
+import * as mies from "./mies.mjs";
+export default 123;

test/extract/acorn/extract-stats.spec.mjs

@@ -0,0 +1,37 @@
+import { deepEqual } from "node:assert/strict";
+import extractStats from "#extract/acorn/extract-stats.mjs";
+import { getStats } from "#extract/acorn/extract.mjs";
+
+describe("[U] extract/acorn/extractStats", () => {
+ it("should return stats for a given AST", () => {
+ const lAST = {
+ body: [{ type: "FunctionDeclaration" }, { type: "VariableDeclaration" }],
+ end: 100,
+ };
+ deepEqual(extractStats(lAST), {
+ topLevelStatementCount: 2,
+ size: 100,
+ });
+ });
+
+ it("should return 0 for empty AST", () => {
+ deepEqual(extractStats({}), {
+ topLevelStatementCount: 0,
+ size: 0,
+ });
+ });
+});
+
+describe("[I] extract/acorn/extract - getStats", () => {
+ it("should return stats for a given file containing valid javascript", () => {
+ const lStats = getStats(
+ { baseDir: "./test/extract/__mocks__" },
+ "extract-stats-testfile.mjs",
+ { extension: ".mjs" },
+ );
+ deepEqual(lStats, {
+ topLevelStatementCount: 5,
+ size: 1010,
+ });
+ });
+});