@moojo/audit-deps

Dependency auditing tool that detects and fixes dependency declaration violations in TypeScript monorepos.

Installation

npm install @moojo/audit-deps

Overview

audit-deps scans module directories for anomalies between package.json declarations and actual import usage in source code. It can detect issues and optionally auto-fix them.

Features

• Missing Dependencies: Detects packages imported in source code but not listed in package.json
• Obsolete Dependencies: Detects packages listed in package.json but not imported anywhere
• Self Imports: Detects when a module imports its own package name (causes compilation issues)
• Deep Imports: Detects imports that reach into another package's internal files
• Local File Import Extensions: Ensures local file imports include .js extension for ESM compatibility
• Type-Only Import Handling: Properly categorizes import type statements as dev dependencies

Usage

Programmatic API

import { auditDeps } from '@moojo/audit-deps'

const result = await auditDeps(
  process.cwd(), // Starting directory
  console.log, // Print function for output
  [], // Specific paths to scan (empty = scan all)
  {
    doFix: false, // Whether to auto-fix violations
    useJson: false, // Output in JSON format
    enableJsImports: true, // Require .js extension on local imports
    resolveFromNpm: true, // Resolve missing package versions from npm
  },
)

// result is 'success' or 'err'

Violation Types

Missing Dependency

A package is imported in source code but not declared in package.json:

Missing Dependency:
   - In File: modules/a/package.json
   - Dependency: lodash
   - This dependency is imported by modules/a/src/utils.ts

Obsolete Dependency

A package is declared in package.json but never imported:

Obsolete Dependency:
   - In File: modules/a/package.json
   - Dependency: unused-lib
   - This dependency is listed but not imported by your code

Self Import

A module imports its own package name:

Self Import:
   - Location: modules/a/src/foo.ts:3:20
   - This file imports its own package (a) which blocks compilation

Deep Import

An import statement reaches into another package's internal files:

Deep Import:
   - Location: modules/a/src/a.ts:1:17
   - Import: b/src/internal
   - This import creates an implicit dependency not declared in package.json

Local File Import Extension

A local file import is missing the .js extension:

Missing .js extension in local import:
   - Location: modules/a/src/a.ts:1:17
   - Import: ./foo
   - Fix: Local file imports must include .js extension for ESM compatibility

Configuration

allowedStaleDeps

You can allow specific dependencies to remain in package.json even if they appear unused by adding an allowedStaleDeps field:

{
  "name": "my-package",
  "dependencies": {
    "runtime-loaded": "1.0.0"
  },
  "allowedStaleDeps": ["runtime-loaded"]
}

This is useful for packages that are loaded dynamically or required by build tools.

License

MIT