fix(doc): re-organizes types folder, improves typing of extract-webpa…

…ck-resolve-config

package.json

@@ -55,31 +55,31 @@
       "import": "./src/main/index.mjs"
     },
     "./config-utl/extract-babel-config": {
-      "types": "./types/extract-babel-config.d.mts",
+      "types": "./types/config-utl/extract-babel-config.d.mts",
       "import": "./src/config-utl/extract-babel-config.mjs"
     },
     "./config-utl/extract-depcruise-config": {
-      "types": "./types/extract-depcruise-config.d.mts",
+      "types": "./types/config-utl/extract-depcruise-config.d.mts",
       "import": "./src/config-utl/extract-depcruise-config/index.mjs"
     },
     "./config-utl/extract-ts-config": {
-      "types": "./types/extract-ts-config.d.mts",
+      "types": "./types/config-utl/extract-ts-config.d.mts",
       "import": "./src/config-utl/extract-ts-config.mjs"
     },
     "./config-utl/extract-webpack-resolve-config": {
-      "types": "./types/extract-webpack-resolve-config.d.mts",
+      "types": "./types/config-utl/extract-webpack-resolve-config.d.mts",
       "import": "./src/config-utl/extract-webpack-resolve-config.mjs"
     },
     "./sample-reporter-plugin": {
-      "types": "./types/stats-reporter-plugin.d.mts",
+      "types": "./types/plugins/stats-reporter-plugin.d.mts",
       "import": "./configs/plugins/stats-reporter-plugin.mjs"
     },
     "./sample-3d-reporter-plugin": {
-      "types": "./types/3d-reporter-plugin.d.mts",
+      "types": "./types/plugins/3d-reporter-plugin.d.mts",
       "import": "./configs/plugins/3d-reporter-plugin.mjs"
     },
     "./mermaid-reporter-plugin": {
-      "types": "./types/mermaid-reporter-plugin.d.mts",
+      "types": "./types/plugins/mermaid-reporter-plugin.d.mts",
       "import": "./src/report/mermaid.mjs"
     }
   },
@@ -93,7 +93,7 @@
     "!src/**/*.hbs",
     "!src/**/*.md",
     "!**/*.DS_Store",
-    "types/*.d.mts",
+    "types/**/*.d.mts",
     "LICENSE",
     "package.json",
     "README.md"

src/config-utl/extract-webpack-resolve-config.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 import { extname } from "node:path";
 import { createRequire } from "node:module";
 import makeAbsolute from "./make-absolute.mjs";
@@ -7,7 +8,7 @@ const require = createRequire(import.meta.url);
 function pryConfigFromTheConfig(
   pWebpackConfigModule,
   pEnvironment,
-  pArguments
+  pArguments,
 ) {
   let lReturnValue = pWebpackConfigModule;
 
@@ -19,7 +20,7 @@ function pryConfigFromTheConfig(
     lReturnValue = pryConfigFromTheConfig(
       pWebpackConfigModule[0],
       pEnvironment,
-      pArguments
+      pArguments,
     );
   }
 
@@ -38,7 +39,7 @@ function suggestModules(pSuggestionList, pWebpackConfigFilename) {
     lReturnValue = lSuggestionList.reduce(
       (pAll, pCurrent) => `${pAll}         - ${pCurrent.module || pCurrent}\n`,
       `\n         Some npm modules that might fix that problem (one of which you'll` +
-        `\n         need so '${pWebpackConfigFilename}' works with webpack anyway):\n`
+        `\n         need so '${pWebpackConfigFilename}' works with webpack anyway):\n`,
     );
   }
   return lReturnValue;
@@ -57,8 +58,8 @@ function tryRegisterNonNative(pWebpackConfigFilename) {
         `\n${suggestModules(
           // eslint-disable-next-line security/detect-object-injection
           interpret.extensions[lConfigExtension],
-          pWebpackConfigFilename
-        )}`
+          pWebpackConfigFilename,
+        )}`,
     );
   }
 }
@@ -95,7 +96,7 @@ async function attemptImport(pAbsoluteWebpackConfigFileName) {
   } catch (pError) {
     throw new Error(
       `The webpack config '${pAbsoluteWebpackConfigFileName}' seems to be not quite valid for use:` +
-        `\n\n          "${pError}"\n`
+        `\n\n          "${pError}"\n`,
     );
   }
 }
@@ -106,24 +107,26 @@ async function attemptImport(pAbsoluteWebpackConfigFileName) {
  * either be a string or a keys-values object)) returns the resolve config
  * from it as an object.
  *
+ * @typedef {{ [key: string]: any } | string} webpackArgumentsType
+ *
  * @param {string} pWebpackConfigFilename
- * @param {string=} pEnvironment
- * @param {string|any=} pArguments
- * @return {any} webpack resolve config as an object
+ * @param {{ [key: string]: any }=} pEnvironment
+ * @param {webpackArgumentsType=} pArguments
+ * @return {Promise<import("enhanced-resolve").ResolveOptions|{}>} webpack resolve config as an object
  * @throws {Error} when the webpack config isn't usable (e.g. because it
  *                 doesn't exist, or because it's invalid)
  */
 export default async function extractWebpackResolveConfig(
   pWebpackConfigFilename,
   pEnvironment,
-  pArguments
+  pArguments,
 ) {
   let lReturnValue = {};
   const lAbsoluteConfigFilename = makeAbsolute(pWebpackConfigFilename);
   const lWebpackConfig = pryConfigFromTheConfig(
     await attemptImport(lAbsoluteConfigFilename),
     pEnvironment,
-    pArguments
+    pArguments,
   );
 
   if (lWebpackConfig.resolve) {

types/extract-babel-config.d.mts → types/config-utl/extract-babel-config.d.mts

@@ -11,7 +11,7 @@
  *         when dependency-cruiser can't yet process it
  */
 export default function extractBabelConfig(
-  pBabelConfigFileName: string,
+  pBabelConfigFileName: string
 ): Promise<object>;
 
 // regarding the rather unspecific _object_ type - this is what's

types/extract-depcruise-config.d.mts → types/config-utl/extract-depcruise-config.d.mts

@@ -1,4 +1,4 @@
-import type { ICruiseOptions } from "./options.d.mts";
+import type { ICruiseOptions } from "../options.mjs";
 
 /**
  * Reads the file with name `pConfigFileName` returns the parsed cruise
@@ -20,5 +20,5 @@ import type { ICruiseOptions } from "./options.d.mts";
 export default function extractDepcruiseConfig(
   pConfigFileName: string,
   pAlreadyVisited?: Set<string>,
-  pBaseDirectory?: string,
+  pBaseDirectory?: string
 ): Promise<ICruiseOptions>;

types/extract-webpack-resolve-config.d.mts → types/config-utl/extract-webpack-resolve-config.d.mts

@@ -1,3 +1,4 @@
+import type { ResolveOptions } from "enhanced-resolve";
 /**
  * Reads the file with name `pWebpackConfigFilename` and (applying the
  * environment `pEnvironment` and the arguments `pArguments` (which can
@@ -13,6 +14,6 @@
  */
 export default function extractWebpackResolveConfig(
   pWebpackConfigFilename: string,
-  pEnvironment?: string,
-  pArguments?: any, // string or a list of arguments
-): Promise<any>;
+  pEnvironment?: { [key: string]: any },
+  pArguments?: { [key: string]: any } | string
+): Promise<ResolveOptions>;

types/configuration.d.mts

@@ -1,5 +1,5 @@
-import type { ICruiseOptions } from "./options.d.mts";
-import type { IFlattenedRuleSet } from "./rule-set.d.mts";
+import type { ICruiseOptions } from "./options.mjs";
+import type { IFlattenedRuleSet } from "./rule-set.mjs";
 
 export interface IConfiguration extends IFlattenedRuleSet {
   /**

types/filter-types.d.mts

@@ -1,4 +1,4 @@
-import type { DependencyType } from "./shared-types.d.mts";
+import type { DependencyType } from "./shared-types.mjs";
 
 export interface IDoNotFollowType {
   /**