DPDM: Dependency Analyzer

Common errors

• Error: dpdm requires Node.js v20.x or higher. You are using v18.x.x.

  cause The installed version of Node.js is older than the minimum required by dpdm v4.x.
  fix Upgrade Node.js to version 20 or newer using `nvm install 20 && nvm use 20` or by updating your Node.js distribution.

• ENOENT: no such file or directory, stat '/path/to/your/project/src/index.ts'

  cause The entry file(s) or glob pattern provided to dpdm do not exist or are incorrect.
  fix Double-check the file paths and glob patterns specified in your dpdm command or API call. Ensure they are relative to the `--context` or `context` option, or are absolute paths.

• TypeError: Cannot read properties of undefined (reading 'resolvedModules') at getDependenciesOfSourceFile

  cause This often indicates a TypeScript version mismatch where dpdm's internal parser struggles with the project's TypeScript syntax or configuration, or an issue with path mapping resolution.
  fix Update dpdm to its latest version, or ensure your project's `tsconfig.json` `compilerOptions.target` and `moduleResolution` settings are standard and well-formed. Verify that the TypeScript version your project uses is compatible with the dpdm version's tested TS version.

• Error: Unable to resolve module: 'src/components/button' in '/path/to/project/src/pages/home.ts'

  cause dpdm could not resolve an import path, possibly due to missing `baseUrl` or `paths` configuration in `tsconfig.json`, or an incorrect `--extensions` setting.
  fix Verify your `tsconfig.json` includes correct `compilerOptions.baseUrl` and `compilerOptions.paths` if you are using path aliases. Ensure `--extensions` (or `extensions` in API) includes all relevant file types for resolution (e.g., `.ts,.tsx,.js,.jsx`).

Warnings

• breaking Version 4.0.1 and subsequent versions require Node.js version 20 or greater to run. Older Node.js environments will not be supported.
  Fix: Upgrade your Node.js runtime environment to version 20 or newer. Use `nvm` or `volta` to manage Node.js versions if needed.
• gotcha dpdm closely tracks TypeScript versions due to its internal parsing mechanism. Using dpdm with a significantly older or newer TypeScript version in your project than what dpdm was built against (e.g., TS 5.6 for dpdm v3.15.0) can lead to parsing errors or incorrect analysis results.
  Fix: Ensure that your project's TypeScript version is compatible with the dpdm version you are using. Check dpdm's release notes for the supported TypeScript version in each major/minor release.
• gotcha The `--skip-dynamic-imports` CLI option (or `skipDynamicImports` API option) has two distinct behaviors: 'circular' only ignores dynamic imports when detecting circular references, while 'tree' ignores them during the initial source file parsing for the full dependency tree. Misunderstanding this can lead to incomplete analysis or unexpected results.
  Fix: Carefully choose between `circular` and `tree` values for `--skip-dynamic-imports` based on whether you want to exclude dynamic imports from only circularity checks or from the entire dependency graph analysis.
• gotcha When using `dpdm` in a CI/CD pipeline, relying solely on its output to `stdout` might not integrate well with build failure conditions. The `--exit-code` option is crucial for making the pipeline fail if circular dependencies are found.
  Fix: Always use `--exit-code circular:1` (or a similar pattern for other checks like unused files) in CI/CD environments to ensure that the build process fails if unwanted dependencies are detected.

Install

• npm install dpdm npm
• yarn add dpdm yarn
• pnpm add dpdm pnpm

Imports

• analyze
  wrong:

  const { analyze } = require('dpdm');

  correct:

  import { analyze } from 'dpdm';

  The primary API function for programmatically analyzing dependencies. Prefer ESM imports.
• AnalyzeOptions

  import type { AnalyzeOptions } from 'dpdm';

  Type definition for the options object passed to the `analyze` function.
• DpdmResult

  import type { DpdmResult } from 'dpdm';

  Type definition for the analysis result object returned by the `analyze` function.

Quickstart

This quickstart demonstrates how to use `dpdm` programmatically to analyze a project for circular dependencies and unused files, showing basic configuration and result handling.

import { analyze } from 'dpdm';
import * as fs from 'node:fs';
import * as path from 'node:path';

const projectRoot = process.cwd();
const srcDir = path.join(projectRoot, 'src');

// Create dummy files for demonstration
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(path.join(srcDir, 'a.ts'), 'import { b } from "./b"; export const a = b + 1;');
fs.writeFileSync(path.join(srcDir, 'b.ts'), 'import { c } from "./c"; export const b = c + 1;');
fs.writeFileSync(path.join(srcDir, 'c.ts'), 'import { a } from "./a"; export const c = a + 1;'); // Circular dependency
fs.writeFileSync(path.join(srcDir, 'd.ts'), 'export const d = 4;'); // Unused file

async function runAnalysis() {
  try {
    const result = await analyze([path.join(srcDir, 'a.ts')], {
      context: projectRoot,
      exclude: 'node_modules',
      circular: true,
      tree: true,
      detectUnusedFilesFrom: path.join(srcDir, '**/*.*')
    });

    console.log('Analysis completed:');
    if (result.circular.length > 0) {
      console.log('Circular dependencies found:', result.circular);
    } else {
      console.log('No circular dependencies found.');
    }
    if (result.unused.length > 0) {
      console.log('Unused files found:', result.unused);
    }
    console.log('Full dependency tree (truncated for brevity):', Object.keys(result.tree).slice(0, 5));
  } catch (error) {
    console.error('Analysis failed:', error);
  } finally {
    // Clean up dummy files
    fs.rmSync(srcDir, { recursive: true, force: true });
  }
}

runAnalysis();