rev-dep 2.4.0-beta.1 → 2.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Mazurek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -49,7 +49,7 @@ Built in Go for speed. Even on large codebases, rev-dep responds almost instantl
 
 You get **exact file paths**, **import chains**, and **clear dependency relationships** — the kind of information you can fix or clean up right away.
 
-### ✅ **Designed for real-world JS/TS**
+### ✅ **Designed for real-world JS/TS with first class monorepo support**
 
 Works with mixed JS/TS projects, path aliases and thousands of files without configuration hassles.
 
@@ -91,7 +91,8 @@ For large project with 500k+ lines of code and 6k+ source code files get checks
 * 📏 **Count actual lines of code (excluding comments and blanks)**
 * 💽 **Node modules disk usage & size analysis**
 * 💡 **Works with both JavaScript and TypeScript**
-* ⚡ **Built for large codebases**
+* ⚡ **Built for large codebases and monorepos**
+* 🏗️ **Supports TypeScript path aliases and package.json imports and exports map**
 
 # **Installation 📦**
 
@@ -216,6 +217,245 @@ rev-dep node-modules missing
 rev-dep node-modules dirs-size
 ```
 
+## Working with Monorepo
+
+Rev-dep provides first-class support for monorepo projects, enabling accurate dependency analysis across workspace packages.
+
+### followMonorepoPackages Flag
+
+The `--follow-monorepo-packages` flag enables resolution of imports from monorepo workspace packages. By default, this flag is set to `false` to maintain compatibility with single-package projects.
+
+```bash
+# Enable monorepo package resolution
+rev-dep circular --follow-monorepo-packages
+rev-dep resolve --file src/utils.ts --follow-monorepo-packages
+rev-dep entry-points --follow-monorepo-packages
+```
+
+When enabled, rev-dep will:
+
+- **Detect workspace packages** automatically by scanning for monorepo configuration
+- **Resolve imports between packages** within the workspace
+- **Follow package.json exports** for proper module resolution
+
+### Exports Map Support
+
+Rev-dep fully supports the `exports` field in package.json files, which is the standard way to define package entry points in modern Node.js projects.
+
+The exports map support includes:
+
+- **Conditional exports** using conditions like `node`, `import`, `default`, and custom conditions
+- **Wildcard patterns** for flexible subpath mapping
+- **Sugar syntax** for simple main export definitions
+- **Nested conditions** for complex resolution scenarios
+
+### Condition Names Flag
+
+To control which conditional exports are resolved, use the `--condition-names` flag. This allows you to specify the priority of conditions when resolving package exports:
+
+```bash
+# Resolve exports for different environments
+rev-dep circular --condition-names=node,import,default
+rev-dep resolve --file src/utils.ts --condition-names=import,node
+rev-dep entry-points --condition-names=default,node,import
+```
+
+The conditions are processed in the order specified, with the first matching condition being used. Common conditions include:
+- `node` - Node.js environment
+- `import` - ES modules
+- `require` - CommonJS
+- `default` - Fallback condition
+- Custom conditions specific to your project or build tools
+
+Example package.json with exports:
+
+```json
+{
+  "name": "@myorg/utils",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./helpers": "./dist/helpers.js",
+    "./types/*": "./dist/types/*.d.ts"
+  }
+}
+```
+
+### How It Works
+
+1. **Monorepo Detection**: When `followMonorepoPackages` is enabled, rev-dep scans for workspace configuration (pnpm-workspace.yaml, package.json workspaces, etc.)
+
+2. **Package Resolution**: Imports to workspace packages are resolved using the package's exports configuration, falling back to main/module fields when exports are not defined
+
+3. **Dependency Validation**: The tool validates that cross-package imports are only allowed when the target package is listed in the consumer's dependencies or devDependencies
+
+4. **Path Resolution**: All paths are resolved relative to their respective package roots, ensuring accurate dependency tracking across the entire monorepo
+
+This makes rev-dep particularly effective for large-scale monorepo projects where understanding cross-package dependencies is crucial for maintaining code quality and architecture.
+
+## Config-Based Checks
+
+Rev-dep provides a configuration system for orchestrating project checks. The config approach is **designed for speed** and is the **preferred way** of implementing project checks because it can execute all checks in a single pass, significantly faster than multiple running individual commands separately.
+
+Available checks are:
+
+- **module boundaries** - check if imports respect module boundaries
+- **circular imports** - check if there are circular imports
+- **orphan files** - check if there are orphan/dead files
+- **unused node modules** - check against unused node modules
+- **missing node modules** - check against missing node modules
+
+Checks are grouped in rules. You can have multiple rules, eg. for each monorepo package.
+
+### Getting Started
+
+Initialize a configuration file in your project:
+
+```bash
+# Create a default configuration file
+rev-dep config init
+```
+
+Behavior of `rev-dep config init`:
+
+- Monorepo root: Running `rev-dep config init` at the workspace root creates a root rule and a rule for each discovered workspace package.
+- Monorepo workspace package or regular projects: Running `rev-dep config init` inside a directory creates config with a single rule with `path: "."` for this directory.
+
+Run all configured checks:
+
+```bash
+# Execute all rules and checks defined in the config
+rev-dep config run
+```
+
+### Configuration Structure
+
+The configuration file (`rev-dep.config.json(c)` or `.rev-dep.config.json(c)`) allows you to define multiple rules, each targeting different parts of your codebase with specific checks enabled.
+
+Here's a comprehensive example showing all available properties:
+
+```jsonc
+{
+  "configVersion": "1.0",
+  "$schema": "https://github.com/jayu/rev-dep/blob/module-boundaries/config-schema/1.0.schema.json?raw=true", // enables json autocompletion
+  "conditionNames": ["import", "default"],
+  "ignoreFiles": ["**/*.test.*"],
+  "rules": [
+    {
+      "path": ".",
+      "followMonorepoPackages": true,
+      "moduleBoundaries": [
+        {
+          "name": "ui-components",
+          "pattern": "src/components/**/*",
+          "allow": ["src/utils/**/*", "src/types/**/*"],
+          "deny": ["src/api/**/*"]
+        },
+        {
+          "name": "api-layer",
+          "pattern": "src/api/**/*",
+          "allow": ["src/utils/**/*", "src/types/**/*"],
+          "deny": ["src/components/**/*"]
+        }
+      ],
+      "circularImportsDetection": {
+        "enabled": true,
+        "ignoreTypeImports": true
+      },
+      "orphanFilesDetection": {
+        "enabled": true,
+        "validEntryPoints": ["src/index.ts", "src/app.ts"],
+        "ignoreTypeImports": true,
+        "graphExclude": ["**/*.test.*", "**/stories/**/*"]
+      },
+      "unusedNodeModulesDetection": {
+        "enabled": true,
+        "includeModules": ["@myorg/**"],
+        "excludeModules": ["@types/**"],
+        "pkgJsonFieldsWithBinaries": ["scripts", "bin"],
+        "filesWithBinaries": ["scripts/check-something.sh"],
+        "filesWithModules": [".storybook/main.ts"],
+        "outputType": "groupByModule"
+      },
+      "missingNodeModulesDetection": {
+        "enabled": true,
+        "includeModules": ["lodash", "axios"],
+        "excludeModules": ["@types/**"],
+        "outputType": "groupByFile"
+      }
+    }
+  ]
+}
+```
+
+### Available Properties
+
+#### Root Level Properties
+- **`configVersion`** (required): Configuration version string
+- **`$schema`** (optional): JSON schema reference for validation
+- **`conditionNames`** (optional): Array of condition names for exports resolution
+- **`ignoreFiles`** (optional): Global file patterns to ignore across all rules. Git ignored files are skipped by default.
+- **`rules`** (required): Array of rule objects
+
+#### Rule Properties
+Each rule can contain the following properties:
+
+- **`path`** (required): Target directory path for this rule (either `.` or path starting with sub directory name)
+- **`followMonorepoPackages`** (optional): Enable monorepo package resolution (default: true)
+- **`moduleBoundaries`** (optional): Array of module boundary rules
+- **`circularImportsDetection`** (optional): Circular import detection configuration
+- **`orphanFilesDetection`** (optional): Orphan files detection configuration  
+- **`unusedNodeModulesDetection`** (optional): Unused node modules detection configuration
+- **`missingNodeModulesDetection`** (optional): Missing node modules detection configuration
+
+#### Module Boundary Properties
+- **`name`** (required): Name of the boundary
+- **`pattern`** (required): Glob pattern for files in this boundary
+- **`allow`** (optional): Array of allowed import patterns
+- **`deny`** (optional): Array of denied import patterns (overrides allow)
+
+#### Detection Options Properties
+
+**CircularImportsDetection:**
+- **`enabled`** (required): Enable/disable circular import detection
+- **`ignoreTypeImports`** (optional): Exclude type-only imports when building graph (default: false)
+
+**OrphanFilesDetection:**
+- **`enabled`** (required): Enable/disable orphan files detection
+- **`validEntryPoints`** (optional): Array of valid entry point patterns (eg. ["src/index.ts", "src/main.ts"])
+- **`ignoreTypeImports`** (optional): Exclude type-only imports when building graph (default: false)
+- **`graphExclude`** (optional): File patterns to exclude from graph analysis
+
+**UnusedNodeModulesDetection:**
+- **`enabled`** (required): Enable/disable unused modules detection
+- **`includeModules`** (optional): Module patterns to include in analysis
+- **`excludeModules`** (optional): Module patterns to exclude from analysis
+- **`pkgJsonFieldsWithBinaries`** (optional): Package.json fields containing binary references (eg. lint-staged). Performs plain-text lookup
+- **`filesWithBinaries`** (optional): File patterns to search for binary usage. Performs plain-text lookup
+- **`filesWithModules`** (optional): Non JS/TS file patterns to search for module imports (eg. shell scripts). Performs plain-text lookup
+- **`outputType`** (optional): Output format - "list", "groupByModule", "groupByFile"
+
+**MissingNodeModulesDetection:**
+- **`enabled`** (required): Enable/disable missing modules detection
+- **`includeModules`** (optional): Module patterns to include in analysis
+- **`excludeModules`** (optional): Module patterns to exclude from analysis
+- **`outputType`** (optional): Output format - "list", "groupByModule", "groupByFile"
+
+### Performance Benefits
+
+The configuration approach provides significant performance advantages:
+
+- **Single Dependency Tree Build**: Builds one comprehensive dependency tree for all rules
+- **Parallel Rule Execution**: Processes multiple rules simultaneously
+- **Parallel Check Execution**: Runs all enabled checks within each rule in parallel
+- **Optimized File Discovery**: Discovers files once and reuses across all checks
+
+This makes config-based checks faster than running individual commands sequentially, especially for large codebases with multiple sub packages.
+
+
 
 ## Reimplemented to achieve 7x-37x speedup
 
@@ -339,6 +579,67 @@ rev-dep circular --ignore-types-imports
 ```
 
 
+### rev-dep config
+
+Create and execute rev-dep configuration files
+
+#### Synopsis
+
+Commands for creating and executing rev-dep configuration files.
+
+#### Options
+
+```
+  -c, --cwd string   Working directory (default "$PWD")
+  -h, --help         help for config
+```
+
+
+### rev-dep config run
+
+Execute all checks defined in (.)rev-dep.config.json(c)
+
+#### Synopsis
+
+Process (.)rev-dep.config.json(c) and execute all enabled checks (circular imports, orphan files, module boundaries, node modules) per rule.
+
+```
+rev-dep config run [flags]
+```
+
+#### Options
+
+```
+      --condition-names strings    List of conditions for package.json imports resolution (e.g. node, imports, default)
+  -c, --cwd string                 Working directory (default "$PWD")
+      --follow-monorepo-packages   Enable resolution of imports from monorepo workspace packages
+  -h, --help                       help for run
+      --package-json string        Path to package.json (default: ./package.json)
+      --tsconfig-json string       Path to tsconfig.json (default: ./tsconfig.json)
+  -v, --verbose                    Show warnings and verbose output
+```
+
+
+### rev-dep config init
+
+Initialize a new rev-dep.config.json file
+
+#### Synopsis
+
+Create a new rev-dep.config.json configuration file in the current directory with default settings.
+
+```
+rev-dep config init [flags]
+```
+
+#### Options
+
+```
+  -c, --cwd string   Working directory (default "$PWD")
+  -h, --help         help for init
+```
+
+
 ### rev-dep entry-points
 
 Discover and list all entry points in the project
@@ -412,6 +713,41 @@ rev-dep files --entry-point src/index.ts
 ```
 
 
+### rev-dep imported-by
+
+List all files that directly import the specified file
+
+#### Synopsis
+
+Finds and lists all files in the project that directly import the specified file.
+This is useful for understanding the impact of changes to a particular file.
+
+```
+rev-dep imported-by [flags]
+```
+
+#### Examples
+
+```
+rev-dep imported-by --file src/utils/helpers.ts
+```
+
+#### Options
+
+```
+      --condition-names strings    List of conditions for package.json imports resolution (e.g. node, imports, default)
+  -n, --count                      Only display the count of importing files
+  -c, --cwd string                 Working directory for the command (default "$PWD")
+  -f, --file string                Target file to find importers for (required)
+      --follow-monorepo-packages   Enable resolution of imports from monorepo workspace packages
+  -h, --help                       help for imported-by
+      --list-imports               List the import identifiers used by each file
+      --package-json string        Path to package.json (default: ./package.json)
+      --tsconfig-json string       Path to tsconfig.json (default: ./tsconfig.json)
+  -v, --verbose                    Show warnings and verbose output
+```
+
+
 ### rev-dep lines-of-code
 
 Count actual lines of code in the project excluding comments and blank lines

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rev-dep",
-  "version": "2.4.0-beta.1",
+  "version": "2.4.0",
   "description": "Trace imports, detect unused code, clean dependencies — all with a super-fast CLI",
   "bin": "bin.js",
   "files": [
@@ -17,9 +17,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@rev-dep/darwin-arm64": "2.4.0-beta.1",
-    "@rev-dep/linux-x64": "2.4.0-beta.1",
-    "@rev-dep/win32-x64": "2.4.0-beta.1"
+    "@rev-dep/darwin-arm64": "2.4.0",
+    "@rev-dep/linux-x64": "2.4.0",
+    "@rev-dep/win32-x64": "2.4.0"
   },
   "keywords": [
     "dependency-analysis",