feat: allow skipping circular import edges

Author: acrazing

README.md

@@ -92,6 +92,12 @@
    dpdm --skip-dynamic-imports circular index.js
    ```
 
+7. Ignore specified imports when finding circular dependencies:
+
+   ```bash
+   dpdm ./src/index.js --skip-imports 'src/a.js:.*' src/c.js:src/d.js
+   ```
+
 ### Options
 
 ```bash
@@ -132,6 +138,8 @@ Options:
       --detect-unused-files-from  this file is a glob, used for finding unused files.       [string]
       --skip-dynamic-imports      Skip parse import(...) statement.
                                                               [string] [choices: "tree", "circular"]
+      --skip-imports              Skip import edges from circular checks. Values are regexp
+                                  ISSUER:DEPENDENCY pairs.                                   [array]
   -h, --help                      Show help                                                [boolean]
 ```
 
@@ -170,15 +178,15 @@ parseDependencyTree('./index', {
     * the parse options
     */
    export interface ParseOptions {
-      context: string;
-      extensions: string[];
-      js: string[];
-      include: RegExp;
-      exclude: RegExp;
-      tsconfig: string | undefined;
-      onProgress: (event: 'start' | 'end', target: string) => void;
-      transform: boolean;
-      skipDynamicImports: boolean;
+     context: string;
+     extensions: string[];
+     js: string[];
+     include: RegExp;
+     exclude: RegExp;
+     tsconfig: string | undefined;
+     onProgress: (event: 'start' | 'end', target: string) => void;
+     transform: boolean;
+     skipDynamicImports: boolean;
    }
 
    export enum DependencyKind {

src/bin/dpdm.ts

@@ -22,8 +22,36 @@ import {
   prettyWarning,
   simpleResolver,
 } from '../utils';
+import type { SkippedImport } from '../utils';
 import { hideBin } from 'yargs/helpers';
 
+function splitSkipImportValue(value: string): string[] {
+  return value.split(',').filter(Boolean);
+}
+
+function normalizeCircularId(context: string, id: string) {
+  const fullPath = path.isAbsolute(id) ? id : path.resolve(context, id);
+  return path.relative(context, fullPath);
+}
+
+function parseSkipImports(
+  skipImports: string[],
+  context: string,
+): SkippedImport[] {
+  return skipImports.map((item) => {
+    const parts = item.split(':');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      throw new TypeError(
+        `skip import should be in the format ISSUER:DEPENDENCY`,
+      );
+    }
+    return [
+      normalizeCircularId(context, parts[0]),
+      normalizeCircularId(context, parts[1]),
+    ];
+  });
+}
+
 async function main() {
   const y = yargs(hideBin(process.argv));
   const argv = await y
@@ -116,6 +144,11 @@ async function main() {
       choices: ['tree', 'circular'],
       desc: 'Skip parse import(...) statement.',
     })
+    .option('skip-imports', {
+      type: 'string',
+      array: true,
+      desc: 'Skip import edges from circular checks. Values are regexp ISSUER:DEPENDENCY pairs.',
+    })
     .alias('h', 'help')
     .wrap(Math.min(y.terminalWidth(), 100))
     .parseAsync();
@@ -150,6 +183,12 @@ async function main() {
   let current = '';
 
   const context = argv.context || process.cwd();
+  const skippedImports = parseSkipImports(
+    ((argv.skipImports as string[] | undefined) || []).flatMap(
+      splitSkipImportValue,
+    ),
+    context,
+  );
 
   function onProgress(event: 'start' | 'end', target: string) {
     switch (event) {
@@ -200,6 +239,7 @@ async function main() {
       const circulars = parseCircular(
         tree,
         argv.skipDynamicImports === 'circular',
+        skippedImports,
       );
       if (argv.output) {
         await fs.outputJSON(

src/utils.spec.ts

@@ -61,11 +61,15 @@ describe('util', () => {
   });
 
   describe('When parsing circular', () => {
-    function dependencyFactory(id: string): Dependency {
+    function dependencyFactory(
+      id: string,
+      issuer: string = '',
+      kind = DependencyKind.StaticImport,
+    ): Dependency {
       return {
-        issuer: '',
+        issuer,
         request: '',
-        kind: DependencyKind.StaticImport,
+        kind,
         id,
       };
     }
@@ -225,5 +229,62 @@ describe('util', () => {
         expect(actual[1]).toMatchObject(['start', 'mid', 'right']);
       });
     });
+
+    describe('When skip imports are specified', () => {
+      it('Should not skip imports when the skip list is empty', () => {
+        const tree = {
+          a: [dependencyFactory('b', 'a')],
+          b: [dependencyFactory('a', 'b')],
+        };
+
+        expect(parseCircular(tree, false, [])).toEqual([['a', 'b']]);
+      });
+
+      it('Should ignore a matching import edge when parsing circulars', () => {
+        const tree = {
+          a: [dependencyFactory('b', 'a')],
+          b: [dependencyFactory('a', 'b')],
+        };
+
+        expect(parseCircular(tree, false, [['b', 'a']])).toEqual([]);
+      });
+
+      it('Should only ignore the specified import edge', () => {
+        const tree = {
+          start: [
+            dependencyFactory('left', 'start'),
+            dependencyFactory('right', 'start'),
+          ],
+          left: [dependencyFactory('start', 'left')],
+          right: [dependencyFactory('start', 'right')],
+        };
+
+        const actual = parseCircular(tree, false, [['left', 'start']]);
+        expect(actual).toHaveLength(1);
+        expect(actual[0]).toMatchObject(['start', 'right']);
+      });
+
+      it('Should support regexp patterns for skipped imports', () => {
+        const tree = {
+          'src/a.js': [
+            dependencyFactory('src/b.js', 'src/a.js'),
+            dependencyFactory('src/c.js', 'src/a.js'),
+          ],
+          'src/b.js': [dependencyFactory('src/a.js', 'src/b.js')],
+          'src/c.js': [dependencyFactory('src/a.js', 'src/c.js')],
+        };
+
+        expect(parseCircular(tree, false, [['src/a.js', '.*']])).toEqual([]);
+      });
+
+      it('Should not match skipped imports by prefix', () => {
+        const tree = {
+          a: [dependencyFactory('bc', 'a')],
+          bc: [dependencyFactory('a', 'bc')],
+        };
+
+        expect(parseCircular(tree, false, [['a', 'b']])).toEqual([['a', 'bc']]);
+      });
+    });
   });
 });

src/utils.ts

@@ -12,6 +12,19 @@ import { Dependency, DependencyTree, ParseOptions } from './types';
 
 const allBuiltins = new Set(builtinModules);
 
+export type SkippedImport = readonly [string, string];
+
+function createSkippedImportsRegExp(
+  skipImports: readonly SkippedImport[],
+): RegExp {
+  if (skipImports.length === 0) {
+    return /$./;
+  }
+  return new RegExp(
+    `^(?:${skipImports.map((item) => item.join(':')).join('|')})$`,
+  );
+}
+
 export const defaultOptions: ParseOptions = {
   context: process.cwd(),
   extensions: ['', '.ts', '.tsx', '.mjs', '.js', '.jsx', '.json'],
@@ -130,8 +143,10 @@ export function shortenTree(
 export function parseCircular(
   tree: DependencyTree,
   skipDynamicImports: boolean = false,
+  skipImports: readonly SkippedImport[] = [],
 ): string[][] {
   const circulars: string[][] = [];
+  const skippedImports = createSkippedImportsRegExp(skipImports);
 
   tree = { ...tree };
 
@@ -147,7 +162,9 @@ export function parseCircular(
         deps.forEach((dep) => {
           if (
             dep.id &&
-            (!skipDynamicImports || dep.kind !== DependencyKind.DynamicImport)
+            (!skipDynamicImports ||
+              dep.kind !== DependencyKind.DynamicImport) &&
+            !skippedImports.test(`${dep.issuer}:${dep.id}`)
           ) {
             visit(dep.id, used.slice());
           }