dependency-cruiser 16.6.0 → 16.7.0-beta-2

package/src/extract/tsc/extract-typescript-deps.mjs

@@ -1,9 +1,14 @@
+/* eslint-disable unicorn/prevent-abbreviations */
 /* eslint-disable max-lines */
 /* eslint-disable no-inline-comments */
 import tryImport from "#utl/try-import.mjs";
 import meta from "#meta.cjs";
 
-/** @type {import("typescript")} */
+/**
+ * @import typescript, {Node} from "typescript"
+ */
+
+/** @type {typescript} */
 const typescript = await tryImport(
   "typescript",
   meta.supportedTranspilers.typescript,
@@ -24,7 +29,7 @@ function isTypeOnlyImport(pStatement) {
 function isTypeOnlyExport(pStatement) {
   return (
     // for some reason the isTypeOnly indicator is on _statement_ level
-    // and not in exportClause as it is in the importClause ¯\_ (ツ)_/¯.
+    // and not in exportClause as it is in the importClause ¯\_(ツ)_/¯.
     // Also in the case of the omission of an alias the exportClause
     // is not there entirely. So regardless whether there is a
     // pStatement.exportClause or not, we can directly test for the
@@ -46,7 +51,7 @@ function isTypeOnlyExport(pStatement) {
 /**
  * Get all import statements from the top level AST node
  *
- * @param {import("typescript").Node} pAST - the (top-level in this case) AST node
+ * @param {Node} pAST - the (top-level in this case) AST node
  * @returns {{module: string; moduleSystem: string; exoticallyRequired: boolean; dependencyTypes?: string[];}[]} -
  *                                  all import statements in the (top level) AST node
  */
@@ -55,7 +60,7 @@ function extractImports(pAST) {
     .filter(
       (pStatement) =>
         typescript.SyntaxKind[pStatement.kind] === "ImportDeclaration" &&
-        Boolean(pStatement.moduleSpecifier),
+        pStatement.moduleSpecifier,
     )
     .map((pStatement) => ({
       module: pStatement.moduleSpecifier.text,
@@ -70,7 +75,7 @@ function extractImports(pAST) {
 /**
  * Get all export statements from the top level AST node
  *
- * @param {import("typescript").Node} pAST - the (top-level in this case) AST node
+ * @param {Node} pAST - the (top-level in this case) AST node
  * @returns {{module: string; moduleSystem: string; exoticallyRequired: boolean; dependencyTypes?: string[];}[]} -
  *                                  all export statements in the (top level) AST node
  */
@@ -79,7 +84,7 @@ function extractExports(pAST) {
     .filter(
       (pStatement) =>
         typescript.SyntaxKind[pStatement.kind] === "ExportDeclaration" &&
-        Boolean(pStatement.moduleSpecifier),
+        pStatement.moduleSpecifier,
     )
     .map((pStatement) => ({
       module: pStatement.moduleSpecifier.text,
@@ -98,7 +103,7 @@ function extractExports(pAST) {
  * Ignores import equals of variables (e.g. import protocol = ts.server.protocol
  * which happens in typescript/lib/protocol.d.ts)
  *
- * @param {import("typescript").Node} pAST - the (top-level in this case) AST node
+ * @param {Node} pAST - the (top-level in this case) AST node
  * @returns {{module: string, moduleSystem: string;exoticallyRequired: boolean;}[]} - all import equals statements in the
  *                                  (top level) AST node
  */
@@ -123,7 +128,7 @@ function extractImportEquals(pAST) {
  * might be wise to distinguish the three types of /// directive that
  * can come out of this as the resolution algorithm might differ
  *
- * @param {import("typescript").Node} pAST - typescript syntax tree
+ * @param {Node} pAST - typescript syntax tree
  * @returns {{module: string, moduleSystem: string}[]} - 'tripple slash' dependencies
  */
 function extractTripleSlashDirectives(pAST) {
@@ -252,7 +257,74 @@ function isTypeImport(pASTNode) {
         "FirstTemplateToken")
   );
 }
-function walk(pResult, pExoticRequireStrings) {
+
+function extractJSDocImportTags(pJSDocTags) {
+  return pJSDocTags
+    .filter(
+      (pTag) =>
+        pTag.tagName.escapedText === "import" &&
+        pTag.moduleSpecifier?.kind &&
+        typescript.SyntaxKind[pTag.moduleSpecifier.kind] === "StringLiteral" &&
+        pTag.moduleSpecifier.text,
+    )
+    .map((pTag) => ({
+      module: pTag.moduleSpecifier.text,
+      moduleSystem: "es6",
+      exoticallyRequired: false,
+      dependencyTypes: ["type-only", "import", "jsdoc", "jsdoc-import-tag"],
+    }));
+}
+
+function extractJSDocBracketImports(pJSDocTags) {
+  return pJSDocTags
+    .filter(
+      (pTag) =>
+        pTag.tagName.escapedText !== "import" &&
+        /* c8 ignore start */
+        typescript.SyntaxKind[pTag.typeExpression?.kind ?? -1] ===
+          "FirstJSDocNode" &&
+        typescript.SyntaxKind[pTag.typeExpression.type?.kind ?? -1] ===
+          "LastTypeNode" &&
+        typescript.SyntaxKind[pTag.typeExpression.type.argument?.kind ?? -1] ===
+          "LiteralType" &&
+        typescript.SyntaxKind[
+          pTag.typeExpression.type.argument?.literal?.kind ?? -1
+        ] === "StringLiteral" &&
+        /* c8 ignore stop*/
+        pTag.typeExpression.type.argument.literal.text,
+    )
+    .map((pTag) => ({
+      module: pTag.typeExpression.type.argument.literal.text,
+      moduleSystem: "es6",
+      exoticallyRequired: false,
+      dependencyTypes: ["type-only", "import", "jsdoc", "jsdoc-bracket-import"],
+    }));
+}
+
+function extractJSDocImports(pJSDocNodes) {
+  const lJSDocNodesWithTags = pJSDocNodes.filter(
+    (pJSDocLine) => pJSDocLine.tags,
+  );
+  const lJSDocImportTags = lJSDocNodesWithTags.flatMap((pJSDocLine) =>
+    extractJSDocImportTags(pJSDocLine.tags),
+  );
+  const lJSDocBracketImports = lJSDocNodesWithTags.flatMap((pJSDocLine) =>
+    extractJSDocBracketImports(pJSDocLine.tags),
+  );
+  return lJSDocImportTags.concat(lJSDocBracketImports);
+}
+
+/**
+ * Walks the AST and collects all dependencies
+ *
+ * @param {Node} pASTNode - the AST node to start from
+ * @param {string[]} pExoticRequireStrings - exotic require strings to look for
+ * @param {boolean} pDetectJSDocImports - whether to detect jsdoc imports
+ * @returns {(pASTNode: Node) => void} - the walker function
+ */
+// eslint-disable-next-line max-lines-per-function
+function walk(pResult, pExoticRequireStrings, pDetectJSDocImports) {
+  // eslint-disable-next-line max-lines-per-function
   return (pASTNode) => {
     // require('a-string'), require(`a-template-literal`)
     if (isRequireCallExpression(pASTNode)) {
@@ -298,7 +370,28 @@ function walk(pResult, pExoticRequireStrings) {
         dependencyTypes: ["type-import"],
       });
     }
-    typescript.forEachChild(pASTNode, walk(pResult, pExoticRequireStrings));
+
+    // /** @import thing from './module' */
+    // /** @import {thing} from './module' */
+    // /** @import * as thing from './module' */
+    // see https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#the-jsdoc-import-tag
+    //
+    // TODO: all the kinds of tags that can have import statements as type declarations
+    //      (e.g. @type, @param, @returns, @typedef, @property, @prop, @arg, ...)
+    // https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
+    if (pDetectJSDocImports && pASTNode.jsDoc) {
+      const lJSDocImports = extractJSDocImports(pASTNode.jsDoc);
+
+      // pResult = pResult.concat(lJSDocImports) looks like the more obvious
+      // way to do this, but it re-assigns the pResult parameter
+      lJSDocImports.forEach((pImport) => {
+        pResult.push(pImport);
+      });
+    }
+    typescript.forEachChild(
+      pASTNode,
+      walk(pResult, pExoticRequireStrings, pDetectJSDocImports),
+    );
   };
 }
 
@@ -306,13 +399,19 @@ function walk(pResult, pExoticRequireStrings) {
  * returns an array of dependencies that come potentially nested within
  * a source file, like commonJS or dynamic imports
  *
- * @param {import("typescript").Node} pAST - typescript syntax tree
+ * @param {Node} pAST - typescript syntax tree
+ * @param {string[]} pExoticRequireStrings - exotic require strings to look for
+ * @param {boolean} pDetectJSDocImports - whether to detect jsdoc imports
  * @returns {{module: string, moduleSystem: string}[]} - all commonJS dependencies
  */
-function extractNestedDependencies(pAST, pExoticRequireStrings) {
+function extractNestedDependencies(
+  pAST,
+  pExoticRequireStrings,
+  pDetectJSDocImports,
+) {
   let lResult = [];
 
-  walk(lResult, pExoticRequireStrings)(pAST);
+  walk(lResult, pExoticRequireStrings, pDetectJSDocImports)(pAST);
 
   return lResult;
 }
@@ -320,19 +419,25 @@ function extractNestedDependencies(pAST, pExoticRequireStrings) {
 /**
  * returns all dependencies in the AST
  *
- * @type {(pTypeScriptAST: (import("typescript").Node), pExoticRequireStrings: string[]) => {module: string, moduleSystem: string, dynamic: boolean}[]}
+ * @type {(pTypeScriptAST: (Node), pExoticRequireStrings: string[], pDetectJSDocImports: boolean) => {module: string, moduleSystem: string, dynamic: boolean}[]}
  */
 export default function extractTypeScriptDependencies(
   pTypeScriptAST,
   pExoticRequireStrings,
+  pDetectJSDocImports,
 ) {
-  return Boolean(typescript)
+  // console.dir(pTypeScriptAST, { depth: 100 });
+  return typescript
     ? extractImports(pTypeScriptAST)
         .concat(extractExports(pTypeScriptAST))
         .concat(extractImportEquals(pTypeScriptAST))
         .concat(extractTripleSlashDirectives(pTypeScriptAST))
         .concat(
-          extractNestedDependencies(pTypeScriptAST, pExoticRequireStrings),
+          extractNestedDependencies(
+            pTypeScriptAST,
+            pExoticRequireStrings,
+            pDetectJSDocImports,
+          ),
         )
         .map((pModule) => ({ dynamic: false, ...pModule }))
     : /* c8 ignore next */ [];

package/src/extract/tsc/extract.mjs

@@ -13,13 +13,14 @@ export function shouldUse({ tsPreCompilationDeps, parser }, pFileName) {
 }
 
 export function extract(
-  { baseDir, exoticRequireStrings, moduleSystems },
+  { baseDir, exoticRequireStrings, moduleSystems, detectJSDocImports },
   pFileName,
   pTranspileOptions,
 ) {
   return extractTypeScriptDeps(
     getASTCached(join(baseDir, pFileName), pTranspileOptions),
     exoticRequireStrings,
+    detectJSDocImports,
   ).filter(({ moduleSystem }) => moduleSystems.includes(moduleSystem));
 }
 

package/src/graph-utl/consolidate-module-dependencies.mjs

@@ -1,6 +1,10 @@
 import { compareRules } from "./compare.mjs";
 import { uniq } from "#utl/array-util.mjs";
 
+/**
+ * @import { IDependency, IModule } from "../../types/cruise-result.mjs";
+ */
+
 function mergeDependency(pLeftDependency, pRightDependency) {
   return {
     ...pLeftDependency,
@@ -30,8 +34,8 @@ function mergeDependencies(pResolvedName, pDependencies) {
 }
 
 /**
- * @param {import('../../types/dependency-cruiser.mjs').IDependency[]} pDependencies
- * @returns {import('../../types/dependency-cruiser.mjs').IDependency[]}
+ * @param {IDependency[]} pDependencies
+ * @returns {IDependency[]}
  */
 function consolidateDependencies(pDependencies) {
   let lDependencies = structuredClone(pDependencies);
@@ -51,8 +55,8 @@ function consolidateDependencies(pDependencies) {
 }
 
 /**
- * @param {import('../../types/dependency-cruiser.mjs').IModule} pModule
- * @returns {import('../../types/dependency-cruiser.mjs').IModule}
+ * @param {IModule} pModule
+ * @returns {IModule}
  */
 export default function consolidateModuleDependencies(pModule) {
   return {

package/src/graph-utl/filter-bank.mjs

@@ -5,6 +5,11 @@ import {
   dependencyMatchesFilter,
 } from "./match-facade.mjs";
 
+/**
+ * @import { IModule } from "../../types/cruise-result.mjs";
+ * @import { IStrictReachesType } from "../../types/strict-filter-types.mjs";
+ */
+
 function includeOnly(pModules, pIncludeFilter) {
   return pIncludeFilter.path
     ? pModules
@@ -33,9 +38,9 @@ function exclude(pModules, pExcludeFilter) {
 }
 /**
  *
- * @param {import("../../types/cruise-result.mjs").IModule[]} pModules
- * @param {import("../../types/strict-filter-types.js").IStrictReachesType} pReachesFilter
- * @returns {import("../../types/cruise-result.mjs").IModule[]}
+ * @param {IModule[]} pModules
+ * @param {IStrictReachesType} pReachesFilter
+ * @returns {IModule[]}
  */
 function filterReaches(pModules, pReachesFilter) {
   const lModuleNamesToReach = pModules
@@ -69,7 +74,6 @@ function tagHighlight(pModules, pHighlightFilter) {
   }));
 }
 
-// eslint-disable-next-line complexity
 export function applyFilters(pModules, pFilters) {
   if (pFilters) {
     let lReturnValue = structuredClone(pModules);

package/src/graph-utl/indexed-module-graph.mjs

@@ -1,14 +1,10 @@
 // @ts-check
 /* eslint-disable security/detect-object-injection */
 /**
- * @typedef {import("../../types/cruise-result.d.mts").IFolderDependency} IFolderDependency
- * @typedef {import("../../types/cruise-result.d.mts").IDependency} IDependency
- * @typedef {import("../../types/cruise-result.d.mts").IFolder} IFolder
- * @typedef {import("../../types/cruise-result.d.mts").IModule} IModule
- * @typedef {import("../../types/shared-types.d.mts").DependencyType} DependencyType
- * @typedef {import("../../types/shared-types.d.mjs").IMiniDependency} IMiniDependency
- *
- * @typedef {(IDependency|IFolderDependency) & {name:string; dependencyTypes?: DependencyType[]}} IEdge
+ * @import { IFolderDependency, IDependency, IFolder, IModule } from "../../types/cruise-result.mjs"
+ * @import { DependencyType, IMiniDependency } from "../../types/shared-types.mjs"
+ 
+* @typedef {(IDependency|IFolderDependency) & {name:string; dependencyTypes?: DependencyType[]}} IEdge
  * @typedef {IModule|IFolder} IModuleOrFolder
  * @typedef {IModuleOrFolder & {dependencies: IEdge[]}} IVertex
  */
@@ -201,7 +197,7 @@ export default class IndexedModuleGraph {
    * @param {Set<string>=} pVisited  Technical parameter - best to leave out of direct calls
    * @return {Array<IMiniDependency>}             see description above
    */
-  #getCycleNew(pInitialSource, pCurrentDependency, pVisited) {
+  #getCycle(pInitialSource, pCurrentDependency, pVisited) {
     let lVisited = pVisited || new Set();
     const lCurrentVertex = this.findVertexByName(pCurrentDependency.name);
     const lEdges = lCurrentVertex.dependencies.filter(
@@ -226,7 +222,7 @@ export default class IndexedModuleGraph {
        */
       (pAll, pDependency) => {
         if (!pAll.some((pSome) => pSome.name === pCurrentDependency.name)) {
-          const lCycle = this.#getCycleNew(
+          const lCycle = this.#getCycle(
             pInitialSource,
             pDependency,
             lVisited.add(pDependency.name),
@@ -266,6 +262,6 @@ export default class IndexedModuleGraph {
     if (!lCurrentDependency) {
       return [];
     }
-    return this.#getCycleNew(pInitialSource, lCurrentDependency);
+    return this.#getCycle(pInitialSource, lCurrentDependency);
   }
 }

package/src/graph-utl/rule-set.mjs

@@ -1,3 +1,7 @@
+/**
+ * @import {IFlattenedRuleSet, IForbiddenRuleType} from '../../types/rule-set.mjs';
+ */
+
 /**
  * Finds the first rule in the rule set that has name pName,
  * and undefined if no such rule exists/ the rule is an 'allowed'
@@ -5,9 +9,9 @@
  *
  * (this thing probably belongs in a model-like folder and not in utl)
  *
- * @param {import("../../types/dependency-cruiser").IFlattenedRuleSet} pRuleSet - The rule set to search in
+ * @param {IFlattenedRuleSet} pRuleSet - The rule set to search in
  * @param {string} pName - The rule name to look for
- * @return {import("../../types/rule-set").IForbiddenRuleType|undefined} - a rule (or 'undefined' if nothing found)
+ * @return {IForbiddenRuleType|undefined} - a rule (or 'undefined' if nothing found)
  */
 export function findRuleByName(pRuleSet, pName) {
   const lNamedRules = (pRuleSet?.forbidden ?? []).concat(
@@ -29,7 +33,7 @@ function ruleHasALicenseLikeAttribute(pRule) {
  *
  * Returns false in all other cases
  *
- * @param {import('../../types/dependency-cruiser').IFlattenedRuleSet} pRuleSet
+ * @param {IFlattenedRuleSet} pRuleSet
  * @return {boolean}
  */
 export function ruleSetHasLicenseRule(pRuleSet) {
@@ -38,9 +42,9 @@ export function ruleSetHasLicenseRule(pRuleSet) {
     (pRuleSet?.allowed ?? []).some(ruleHasALicenseLikeAttribute)
   );
 }
+
 /**
- *
- * @param {import('../../types/dependency-cruiser').IFlattenedRuleSet} pRuleSet
+ * @param {IFlattenedRuleSet} pRuleSet
  * @return {boolean}
  */
 export function ruleSetHasDeprecationRule(pRuleSet) {

package/src/main/cruise.mjs

@@ -1,4 +1,4 @@
-/* eslint-disable no-return-await, no-magic-numbers */
+/* eslint-disable no-magic-numbers */
 import { assertCruiseOptionsValid } from "./options/assert-validity.mjs";
 import { normalizeCruiseOptions } from "./options/normalize.mjs";
 import reportWrap from "./report-wrap.mjs";
@@ -65,7 +65,7 @@ export default async function cruise(
     import("#enrich/index.mjs"),
   ]);
 
-  if (Boolean(lCruiseOptions.ruleSet)) {
+  if (lCruiseOptions.ruleSet) {
     bus.summary("parsing rule set", c(4));
     lCruiseOptions.ruleSet = normalizeRuleSet(
       assertRuleSetValid(lCruiseOptions.ruleSet),

package/src/main/format.mjs

@@ -21,6 +21,5 @@ export default async function format(pResult, pFormatOptions = {}) {
 
   validateResultAgainstSchema(pResult);
 
-  // eslint-disable-next-line no-return-await
   return await reportWrap(pResult, lFormatOptions);
 }

package/src/main/options/assert-validity.mjs

@@ -2,6 +2,10 @@
 import safeRegex from "safe-regex";
 import { getAvailableReporters } from "#report/index.mjs";
 
+/**
+ * @import { ICruiseOptions, IFormatOptions } from "../../../types/options.mjs";
+ */
+
 const MODULE_SYSTEM_LIST_RE = /^(?:(?:cjs|amd|es6|tsd)(?:,|$)){1,4}/gi;
 const VALID_DEPTH_RE = /^\d{1,2}$/g;
 
@@ -30,10 +34,10 @@ function deepMerge(pTarget, pSource) {
 
 function assertModuleSystemsValid(pModuleSystems) {
   if (
-    Boolean(pModuleSystems) &&
+    pModuleSystems &&
     Array.isArray(pModuleSystems) &&
     !pModuleSystems.every((pModuleSystem) =>
-      Boolean(pModuleSystem.match(MODULE_SYSTEM_LIST_RE)),
+      pModuleSystem.match(MODULE_SYSTEM_LIST_RE),
     )
   ) {
     throw new Error(
@@ -43,7 +47,7 @@ function assertModuleSystemsValid(pModuleSystems) {
 }
 
 function assertRegExpSafety(pPattern) {
-  if (Boolean(pPattern) && !safeRegex(pPattern)) {
+  if (pPattern && !safeRegex(pPattern)) {
     throw new Error(
       `The pattern '${pPattern}' will probably run very slowly - cowardly refusing to run.\n`,
     );
@@ -52,7 +56,7 @@ function assertRegExpSafety(pPattern) {
 
 function assertOutputTypeValid(pOutputType) {
   if (
-    Boolean(pOutputType) &&
+    pOutputType &&
     !getAvailableReporters().includes(pOutputType) &&
     !pOutputType.startsWith("plugin:")
   ) {
@@ -61,7 +65,7 @@ function assertOutputTypeValid(pOutputType) {
 }
 
 function assertMaxDepthValid(pDepth) {
-  if (Boolean(pDepth) && !pDepth.toString().match(VALID_DEPTH_RE)) {
+  if (pDepth && !pDepth.toString().match(VALID_DEPTH_RE)) {
     throw new Error(
       `'${pDepth}' is not a valid depth - use an integer between 0 and 99`,
     );
@@ -73,7 +77,7 @@ function assertFocusDepthValid(pFocusDepth) {
   const lMaxFocusDepth = 99;
 
   if (
-    Boolean(pFocusDepth) &&
+    pFocusDepth &&
     (Number.isNaN(lFocusDepth) ||
       lFocusDepth < 0 ||
       lFocusDepth > lMaxFocusDepth)
@@ -96,12 +100,12 @@ function assertPathsSafety(pFilterOption) {
 /**
  * @param {any} pOptions
  * @throws {Error}
- * @returns {import("../../../types/dependency-cruiser.js").ICruiseOptions}
+ * @returns {ICruiseOptions}
  */
 export function assertCruiseOptionsValid(pOptions) {
   let lReturnValue = {};
 
-  if (Boolean(pOptions)) {
+  if (pOptions) {
     // necessary because can slip through the cracks when passed as a cli parameter
     assertModuleSystemsValid(pOptions.moduleSystems);
 
@@ -132,7 +136,7 @@ export function assertCruiseOptionsValid(pOptions) {
 
 /**
  *
- * @param {import("../../../types/dependency-cruiser.js").IFormatOptions} pFormatOptions
+ * @param {IFormatOptions} pFormatOptions
  * @throws {Error}
  */
 export function assertFormatOptionsValid(pFormatOptions) {

package/src/main/options/defaults.mjs

@@ -3,6 +3,7 @@ export default {
   validate: false,
   maxDepth: 0,
   moduleSystems: ["es6", "cjs", "tsd", "amd"],
+  detectJSDocImports: false,
   tsPreCompilationDeps: false,
   preserveSymlinks: false,
   combinedDependencies: false,

package/src/main/options/normalize.mjs

@@ -3,6 +3,14 @@ import { normalizeREProperties } from "../helpers.mjs";
 import defaults from "./defaults.mjs";
 import { uniq } from "#utl/array-util.mjs";
 
+/**
+ * @import { ICruiseResult } from "../../../types/cruise-result.mjs";
+ * @import { ICruiseOptions, IFormatOptions } from "../../../types/options.mjs";
+ * @import { IStrictCruiseOptions, IStrictFormatOptions } from "../../../types/strict-options.mjs";
+ * @import { IForbiddenRuleType, IFlattenedRuleSet } from "../../../types/rule-set.mjs";
+ * @import { ICacheOptions } from "../../../types/cache-options.mjs";
+ */
+
 const DEFAULT_CACHE_FOLDER = "node_modules/.cache/dependency-cruiser";
 const DEFAULT_CACHE_STRATEGY = "metadata";
 
@@ -65,7 +73,7 @@ function normalizeCollapse(pCollapse) {
 }
 
 function normalizeFocusDepth(pFormatOptions) {
-  /** @type  {import("../../../types/dependency-cruiser.js").IFormatOptions}*/
+  /** @type {IFormatOptions}*/
   let lFormatOptions = structuredClone(pFormatOptions);
   if (Object.hasOwn(lFormatOptions, "focusDepth")) {
     if (lFormatOptions?.focus) {
@@ -81,7 +89,7 @@ function normalizeFocusDepth(pFormatOptions) {
 
 /**
  *
- * @param {import("../../../types/dependency-cruiser.js").IForbiddenRuleType} pRule
+ * @param {IForbiddenRuleType} pRule
  * @returns {boolean}
  */
 function hasMetricsRule(pRule) {
@@ -96,7 +104,7 @@ function hasMetricsRule(pRule) {
 
 /**
  *
- * @param {import("../../../types/dependency-cruiser.js").IFlattenedRuleSet} pRuleSet
+ * @param {IFlattenedRuleSet} pRuleSet
  * @returns {boolean}
  */
 function ruleSetHasMetricsRule(pRuleSet) {
@@ -109,7 +117,7 @@ function ruleSetHasMetricsRule(pRuleSet) {
 
 /**
  *
- * @param {import('../../../types/dependency-cruiser.js').ICruiseOptions} pOptions
+ * @param {ICruiseOptions} pOptions
  * @returns Boolean
  */
 function reporterShowsMetrics(pOptions) {
@@ -122,7 +130,7 @@ function reporterShowsMetrics(pOptions) {
 /**
  * Determines whether (instability) metrics should be calculated
  *
- * @param {import('../../../types/dependency-cruiser.js').ICruiseOptions} pOptions
+ * @param {ICruiseOptions} pOptions
  * @returns Boolean
  */
 function shouldCalculateMetrics(pOptions) {
@@ -135,8 +143,8 @@ function shouldCalculateMetrics(pOptions) {
 }
 
 /**
- * @param {string|boolean|Partial<import("../../../types/cache-options.js").ICacheOptions>} pCacheOptions
- * @returns {import("../../../types/cache-options.js").ICacheOptions}
+ * @param {string|boolean|Partial<ICacheOptions>} pCacheOptions
+ * @returns {ICacheOptions}
  */
 function normalizeCacheOptions(pCacheOptions) {
   let lNormalizedCacheOptions = pCacheOptions;
@@ -163,12 +171,12 @@ function normalizeCacheOptions(pCacheOptions) {
 
 /**
  *
- * @param {import('../../../types/options.mjs').ICruiseOptions} pOptions
+ * @param {ICruiseOptions} pOptions
  * @param {string[]} pFileAndDirectoryArray
- * @returns {import('../../../types/strict-options.js').IStrictCruiseOptions}
+ * @returns {IStrictCruiseOptions}
  */
 export function normalizeCruiseOptions(pOptions, pFileAndDirectoryArray = []) {
-  /** @type {import('../../../types/strict-options.js').IStrictCruiseOptions} */
+  /** @type {IStrictCruiseOptions} */
   let lReturnValue = {
     baseDir: process.cwd(),
     ...defaults,
@@ -211,14 +219,16 @@ export function normalizeCruiseOptions(pOptions, pFileAndDirectoryArray = []) {
   if (lReturnValue.cache) {
     lReturnValue.cache = normalizeCacheOptions(lReturnValue.cache);
   }
+  if (lReturnValue.detectJSDocImports) {
+    lReturnValue.parser = "tsc";
+  }
 
   return normalizeFocusDepth(lReturnValue);
 }
 
 /**
- *
- * @param {import("../../../types/dependency-cruiser.js").IFormatOptions} pFormatOptions
- * @returns {import("../../../types/strict-options.js").IStrictFormatOptions}
+ * @param {IFormatOptions} pFormatOptions
+ * @returns {IStrictFormatOptions}
  */
 export function normalizeFormatOptions(pFormatOptions) {
   let lFormatOptions = structuredClone(pFormatOptions);

package/src/main/report-wrap.mjs

@@ -6,10 +6,15 @@ import { compareModules } from "#graph-utl/compare.mjs";
 import stripSelfTransitions from "#graph-utl/strip-self-transitions.mjs";
 
 /**
- *
- * @param {import('../../types/dependency-cruiser.js').ICruiseResult} pResult
- * @param {import('../../types/dependency-cruiser.js').IFormatOptions} pFormatOptions
- * @returns {import('../../types/dependency-cruiser.js').ICruiseResult}
+ * @import { ICruiseResult } from "../../types/cruise-result.mjs";
+ * @import { IFormatOptions } from "../../types/options.mjs";
+ * @import { IReporterOutput } from "../../types/dependency-cruiser.mjs";
+ */
+
+/**
+ * @param {ICruiseResult} pResult
+ * @param {IFormatOptions} pFormatOptions
+ * @returns {ICruiseResult}
  */
 function reSummarizeResults(pResult, pFormatOptions) {
   let lModules = applyFilters(pResult.modules, pFormatOptions);
@@ -44,9 +49,9 @@ function getReporterSection(pOutputType) {
 
 /**
  *
- * @param {import("../..).ICruiseResult} pResult result of a previous run of dependency-cruiser
- * @param {import("../../types/dependency-cruiser.js").IFormatOptions} pFormatOptions
- * @returns {import("../../types/dependency-cruiser.js").IReporterOutput}
+ * @param {ICruiseResult} pResult result of a previous run of dependency-cruiser
+ * @param {IFormatOptions} pFormatOptions
+ * @returns {IReporterOutput}
  */
 export default async function reportWrap(pResult, pFormatOptions) {
   const lReportFunction = await getReporter(pFormatOptions.outputType);