dependency-cruiser

🐛 fixes

• 4dffca28 fix(doc): adds type exports for config-utl (babel, depcruise, webpack)

👷 maintenance

♻️ life cycle management

• 04202b27 build(npm): updates external dependencies

💻 DX

• cb87dfcf chore(gitignore): adds .clinic to folders to ignore
• aaf4e53e chore(.gitattributes): tellss linguist what's generated, what's documentation
• 1381506e chore(package.json): store format tmp file somewhere in node_modules

🔒 shasum of the package as published on npmjs: 8ecfe1b82d15ea3bacae4d5a3af20d157d5a79b0

🐛 fixes

• 399eba72 fix(doc): corrects extract-ts-config return type also in tsdoc
• 80a2f8d3 fix(types): adds root and extract-ts-config types (#809) - thank you @mrmckeb for finding the bug and creating the pull request for this!

type exports for the other config-utl (babel, webpack, dependency-cruiser) will follow in a separate patch release

👷 maintenance

• a36b968a build(npm): updates external dependencies
• bd43513d fix(build): lists all sources for the json schema in the Makefile
• 58b44e4a chore: converts the 'unlimited' self cruise config from json to esm
• f16f4256 chore: correctly configures self-cruise to use 'import' condition in enhanced-resolve options

🔏 shasum of the package as published on npmjs: b13ef98ddcd2a9ab4c2478526bc010b8420898b7

To keep dependency-cruiser future proof (and sweeter to use) it was necessary to make some breaking changes in v13.

Most of the breaking changes impact only the API/ library. We've worked hard to avoid it, but some affect the CLI as well.

Summary

• Improvements
  • Support for ESM in dependency-cruiser, babel and webpack configurations
  • No need to pass --config anymore
  • dot reporters: dynamic dependencies show up as dotted lines
  • Performance improvements
• Breaking changes
  • breaking for both CLI and API
    • BREAKING: Dropped support for node 14
    • BREAKING: Dropped support for yarn 1 plug'n play
    • BREAKING: Not passing --config now means 'use default configuration file'
    • BREAKING: For glob patterns on windows use forward slashes
  • breaking: API only
    • BREAKING: API is ESM only
    • BREAKING: API is async
    • BREAKING: cruise signature change

🔏 shasum of the package as published on npmjs: 4ece1a93c4e954f30350cbb99fd62497cb705e51

Improvements

Support for ESM in dependency-cruiser, babel and webpack configurations

As dependency-cruiser itself is now written in ESM, it can now also read .dependency-cruiser, babel and webpack configurations in ESM, so you can write them in more modern JavaScript if you want to. Previously supported formats (commonjs, json5 etc) remain supported

No need to pass --config anymore

In previous versions, even when you had a dependency-cruiser configuration with one of the default names, you still need to pass --config on the command line to tell it to use that configuration. As of version 13 this is not necessary anymore. Otherwise, the --config option still work as it did before.

If you want to run the dependency-cruiser CLI without a configuration file you'll have to explicitly pass it --no-config.

Let me know if you do! I'm interested in these use cases.

dot reporters: dynamic dependencies show up as dotted lines

This was already possible - in v13, we've made it the default as it proved useful to distinguish dynamic imports from regular ones. See #801 for details.

Performance improvements

When I converted dependency-cruiser from commonjs to ESM (on node 19) it turned out dependency-cruiser's self scan took longer than it did before the conversion. Dependency-cruiser's performance-log and closer analysis with node --cpu-prof showed that most of the extra time was added at startup time, importing modules. Because I set myself as a goal to have v13 at least as fast as v12 I took a closer look at what was loaded, that might not be necessary at startup.

#795: lazy loading own code: (-100ms)

• typically you only run dependency-cruiser with one reporter at a time. Because we're using static imports, however, all reporters were loaded, some of which are reasonably large - taking import parse time. By dynamically importing only the one reporter we need, and only when we needed it we shaved of ~40ms from the startup time.
• After having run --init once, you're not going to need it anymore. The init code was statically imported, though. Dynamically importing it only when --init was engaged shaved off ~40ms of regular startup time.
• If you don't run with caching (you should, it's awesome) - caching code shouldn't be imported either - lazy loading that saves ~20ms.

defer loading analytical modules (-100ms - -700ms for cache only runs)

I also realized dependency-cruiser's serving 100% from cache scenario hardly needs to run any static analysis code. Lazy loading these modules till after we've established we need them shaves off ~100ms - ~700ms from 100% from cache runs. The 700ms is extreme though - it's because in dependency-cruiser's self scan babel, vue, svelte, typescript, swc and even coffeescript are available at the same time. I pity you if your real live project has this as well...

It is possible to go deeper here and lazy load the individual transpilers as well, making dependency-cruiser's self-scan nice and fast but the gain in practical situations (where you have only one or two of them in place) would be limited, unless there's a transpiler installed you don't use in your setup (but e.g. only have because a devDependency has it - babel is a logical candidate for this). This improvement might come in a future version of dependency-cruiser.

Breaking changes: CLI and API

Dropped support for node 14

Nodejs 14 is end of life by the end of April 2023 (source). This will mean that most projects will by then have moved to higher versions. If you can't move to nodejs 14 you can keep using dependency-cruiser v12 for a while.

Dropped support for yarn 1 plug'n play

Yarn 1 is still nominally maintained - the yarn team encourages everyone to migrate to yarn 3, which is now maintained for a longer time than yarn 1 ever was. While yarn 1 itself still works fantastically, its pnp implementation won't keep up with new developments in the node landscape (e.g. the node: prefix doesn't work, ES modules don't work) - they do work in later versions of yarn, so if you're still on yarn 1 with PnP you probably want to upgrade to yarn 3 anyway.

To be clear:

• dependency-cruiser >= v13 still works with yarn 3 (and 2) plug'n play . We actively maintain an integration test to ensure it keeps doing so.
• depencency-cruiser >= v13 will keep running in yarn 1 installations that don't have plug'n play engaged. Even if PnP is engaged, it probably would still work when you 'eject' dependency-cruiser from PnP.
• dependency-cruiser <= v12 will still run with yarn 1 + PnP

Not passing --config now means 'use default configuration file'

In previous versions, even when you had a dependency-cruiser configuration with one of the default names, you still need to pass --config on the command line to tell it to use that configuration. This was confusing to many because it's different from most other tools out there in the same space do it.

As of version 13 this is not necessary anymore to pass a --config option to read the default configuration. Otherwise, the --config option still work as it did before.

If you want to run the dependency-cruiser CLI without a configuration file you'll have to explicitly pass it --no-config.

Let me know if you do! I'm interested in these use cases.

For glob patterns on windows use forward slashes

We've bumped to the most recent version of node-glob which has a breaking change where it doesn't accept \ as path separators anymore - and instead advises to use forward slashes (/) in stead.

API only

API is ESM only

Dependency-cruiser is now implemented in ESM - which means that it can only be called from ESM code anymore. I've been looking for ways to compile it down to commonjs, but the transpiler chains I've tried so far can't (e.g. by refusing to convert top level awaits).

API is async (cruise, format, config-utl)

Because in ESM (dynamically) importing modules is an asynchronous affair, all dependency-cruiser interfaces that weren't already had to become asynchronous as well, with the exception of the configuration utility to extract TypeScript configurations.

For an example - see Example to call cruise.

cruise signature change

Apart from becoming asynchronous, we've rationalised the parameters to cruise. In the old interface the fourth parameter was reserved to passing a (normalized) TypeScript configuration only, while having no room to pass a babel configuration or any other (future) transpilation configuration.

The new interface makes the fourth parameter an object that can take a tsConfig, a babelConfig, or both of them.

See example to call cruise below to see how a call could look right now.

Example call to cruise

Before:

import { cruise } from 'dependency-cruiser';
import extractDepcruiseConfig from "dependency-cruiser/config-utl/extract-depcruise-config";
import extractTSConfig from "dependency-cruiser/config-utl/extract-ts-config";
import extractWebpackResolveConfig from "dependency-cruiser/config-utl/extract-webpack-resolve-config"
import extractBabelConfig from "dependency-cruiser/config-utl/extract-babel-config";

const lCruiseOptions = {
  // ...
};

const lResult = cruise(
  ["src", "test"],
  await extractDepcruiseConfig("./.dependency-cruiser.js"),
  extractWebpackResolveConfig("webpack.config.js"),
  extractTSConfig("./tsconfig.json"),
  // not possible to pass a babel configuration
  }
);

After:

import { cruise } from "dependency-cruiser";
import extractDepcruiseConfig from "dependency-cruiser/config-utl/extract-depcruise-config";
import extractTSConfig from "dependency-cruiser/config-utl/extract-ts-config";
import extractWebpackResolveConfig from "dependency-cruiser/config-utl/extract-webpack-resolve-config";
import extractBabelConfig from "dependency-cruiser/config-utl/extract-babel-config";

const lResult = await cruise(
  ["src", "test"],
  await extractDepcruiseConfig("./.dependency-cruiser.js"),
  await extractWebpackResolveConfig("webpack.config.js"),
  {
    tsConfig: extractTSConfig("./tsconfig.json"),
    babelConfig: await extractBabelConfig("./babel.conf.json"),
  }
);

List of changes

• 5a62d737 chore(lint): disables exports-last rule
• a5c2bb56 feature(progress): some more tweaks to the usability of the performance-log
• 9329ae45 build(npm): updates external dependencies
• faaadeaa chore: replaces references to the develop branch with main
• 145527dc doc(cache): adds tsdoc & checks on it
• cfb82546 chore: replaces references to the master branch with develop
• 56fd1113 chore(ci): removes v13 as integration branch and adds main
• b092d70f fix(types): adds mainFields and mainFiles to the enhancedResolveOptions in ICruiseOptions
• 4556fe3f fix(enrich): adds used tsconfig to options used + adds it & babelConfig, webpackConfig to IConfiguration type (#805)
• 8bac684a doc(report): corrects description of the null reporter
• 7cb21dd8 13.0.0-beta-7
• 4fdaf687 perf(extract): splits transpiler availability from execution (#804)
• ecd5563a fix(schema|types): adds null reporter to schema and types
• 5d62d585 fix(schema|types): adds 'checksum' attribute to the module schema (#803)
• 2380954c doc(progress): copy edit of the first step
• df0267d4 13.0.0-beta-6
• d4d6f7c1 refactor(cache): makes git operations in metadata-strategy async
• d408208e refactor(cache): makes read and write async
• 78e6f6fa build(npm): updates external dependencies
• 115ec7bc refactor(progress): improves progress logging DX
• c1c0feae bugfix(cache): handles empty known violations arrays
• 220e0a36 13.0.0-beta-5
• 8d23c9ed doc(extract): improves typing of the meta interface
• 00965eef refactor(config-utl): makes babel json5 configs and known violations read async as well
• 52f5fa04 bugfix(enrich): removes superfluous trailing argument
• bea4ce66 chore: makes yarn --silent by default
• 4e57f890 feature(progress): adds visual aides to performance-log listener
• 72ce164a feature(report): adds a 'null' reporter (#802)
• 12738f55 feature(report): in dot reporters, by default makes dynamic dependencies dashed lines (#801)
• fc6119f9 perf(main): splits off cruise & format in their own modules (#800)
• 68526f30 doc: makes readme backwards compatible (#799)
• 307c307b perf(cli): reads webpack, typescript and babel config options in parallel (#797)
• 8a89bd8e refactor(wrap-stream-in-html): read template elements asynchronously
• a4063bcf 13.0.0-beta-4
• 44c34283 build(npm): updates external dependencies
• 7611a4f9 perf(cli|main): lazy loads config mangling, extract and enrich steps (#796)
• 2fea4985 perf(cli|report): lazy loads --init, reporter and caching code (#795)
• a64ca146 13.0.0-beta-3
• 4a36b7f6 ci: snoozes node 'this is experimental' warnings for esm c.s.
• b8f898aa doc(extract): document why we're using 'reduces' instead of a 'maps' while gathering initial sources
• 6e14233a build(npm): updates external dependencies
• 4b472206 chore(test): sets mocha reporter to 'dot'
• b7456859 chore(ci): replaces node 19 with node 20
• 2a7e7ce8 13.0.0-beta-2
• 1ec9e343 build(npm): update external dependencies
• 947fb348 refactor(report): makes csv reporter less OS dependent (#793)
• 290923b9 feature(config-utl): enables webpack configurations in ESM format (#792)
• cd7eff75 refactor(cli): replaces deprecated substr with substring
• 521ffe03 chore: removes commonjs remnants (#791)
• d46f5d2e refactor: uses qualified imports for imports from node native modules (#790)
• b4f7e25d 13.0.0-beta-1
• 0dc39fd4 fix(tools): makes sample and fixture generators work with the new interfaces
• 96f7ac07 build(npm): update external dependencies
• 9041d037 refactor(extract): converts svelte helper to esm
• 70008e23 refactor(utl): converts to esm (#789)
• 13ae3755 refactor(graph-utl): converts to esm (#788)
• 8c783310 refactor(validate): converts to esm (#787)
• 892cfa56 refactor(enrich): converts to esm (#786)
• 1adefbe7 doc(report): changes copy of instructions what to do with ignored violations
• 912892db refactor(extract): converts svelte wrapper to esm (#785)
• 3c16e7d6 refactor(cli): converts hbs calling code in init-config to esm (#783)
• 3c8c1d6a refactor(report): converts to esm (#782)
• e33a80f5 bugfix: lets several tools ignore the newly named and generated json-schemas-as-esm
• a8872a01 bugfix(npm): sets main to the renamed main/index module
• f4ca4df0 refactor(tools): converts the generated json schema's to esm (#781)
• 9f794e7f refactor(main): converts to esm (#780)
• c311f8b2 chore: updates c8 configuration to renamed files
• b5e2ab1e refactor(report): converts RE for reporter plugins to something more readable
• 89a03fdf refactor(cache): converts to esm (#779)
• 77b74247 refactor: uses node: protocol for all node native module imports (#778)
• ce077a7a refactor(extract): removes default export from meta (#777)
• 411adf7a refactor(extract): moves utl/* into one helpers.mjs (#776)
• 6c7de701 refactor(extract): moves get-manifest (#775)
• dc211d08 refactor(extract): converts to esm (#774)
• e1a61cd4 refactor: replaces cruise function with signature from futureCruise BREAKING (#773)
• 701e020e chore(config-utl): converts to esm (#772)
• 12963a95 feature(cli): removes the necessity to pass --config to read the deafult configuration file BREAKING (#771)
• 822afeb9 chore(cli): converts to esm (#765)
• 1b5c929d build(npm): bumps glob to latest BREAKING (#770)
• 7e354f6d chore: de-supports node 14 BREAKING
• 687f9fcd chore(ci): adds the v13 branch to the ones to check all the things on
• 9ec0025c chore: de-support yarn PnP version 1 BREAKING (#769)

👷 maintenance

• 311e0feb build(npm): updates external dependencies
• b99ab849 chore: replaces references to develop, master branches with v12
• 11f47c6d chore(ci): adds node 20 to build matrix, sets branches to existing ones

🔏 shasum of the package as published on npmjs: 1596f4b7cb186ec33388b9d13aeba751935d40e1

🐛 fixes

• 168e025a fix(enrich): adds used tsconfig to options used + adds it & babelConfig, webpackConfig to IConfiguration type (#805) (backport from v13)

📖 documentation

• e3cb9272 fix(types): adds mainFields and mainFiles to the enhancedResolveOptions in ICruiseOptions (backport from v13)

👷 maintenance

• 64157568 build(npm): updates external devDependencies
• 087fe8ed doc(report): corrects description of the null reporter (backport from v13

🔏 shasum of the package as published on npmjs: 6131ff18b737df25c41bdfdfbfe4eb3610cbf358

See #794

Changes since v13.0.0-beta-5

• 4fdaf687 perf(extract): splits transpiler availability from execution (#804)
• ecd5563a fix(schema|types): adds null reporter to schema and types
• 5d62d585 fix(schema|types): adds 'checksum' attribute to the module schema (#803)
• 2380954c doc(progress): copy edit of the first step

📯 We'll soon be releasing dependency-cruiser v13, which is in beta right now.

• If you want to test v13 beta: you're welcome to! Add dependency-cruiser@beta to your development dependencies.
• see #794 for details & as a thread to post findings regarding v13.

Meanwhile here's still a v12 release. Most of the items are back-ports from the v13 beta - it might be a while before v13 is out of beta, and these items will be useful for users of v12 as well.

✨ features

• 3108902f feature(progress): moves times closer to message in performance-log (back-port)
• 489f9cf8 feature(report): adds a 'null' reporter (back-port)

🐛 fixes

• 6c5dc62d bugfix(cache): handles empty known violations arrays (back-port)
• 9ebfc4fc fix(schema|types): adds null reporter to schema and types (back-port)
• deb7266a fix(schema|types): adds 'checksum' attribute to the module schema (#803) (back-port)

👷 maintenance

♻️ life cycle management

• 945f4a9f build(npm): updates external dependencies

🏗️ ci & dx

• be49230f chore: makes yarn --silent by default (back-port)
• f13beb18 chore: snoozes nodejs module warnings while running tests (back-port)

🔏 shasum of the package as published on npmjs: 99810305b444a94d18dd07550f4e4f84e6366aee

See #794

Changes since v13.0.0-beta-5

🐛 fixes

• c1c0feae bugfix(cache): handles empty known violations arrays

👷 maintenance

• d4d6f7c1 refactor(cache): makes git operations in metadata-strategy async
• d408208e refactor(cache): makes read and write async
• 78e6f6fa build(npm): updates external dependencies
• 115ec7bc refactor(progress): improves progress logging DX

See #794.

Additions a.c.t. beta-4:

✨ features

• 4e57f890 feature(progress): adds visual aides to performance-log listener
• 72ce164a feature(report): adds a 'null' reporter (#802)
• 12738f55 feature(report): in dot reporters, by default makes dynamic dependencies dashed lines (#801)

📖 documentation

• 8d23c9ed doc(extract): improves typing of the meta interface
• 68526f30 doc: makes readme backwards compatible (#799)

👷 maintenance

• 52f5fa04 bugfix(enrich): removes superfluous trailing argument
• bea4ce66 chore: makes yarn --silent by default

🏎️ making things a bit faster

• 00965eef refactor(config-utl): makes babel json5 configs and known violations read async as well
• fc6119f9 perf(main): splits off cruise & format in their own modules (#800)
• 307c307b perf(cli): reads webpack, typescript and babel config options in parallel (#797)
• 8a89bd8e refactor(wrap-stream-in-html): read template elements asynchronously

See #794

a.c.t. the previous beta release this adds two performance improvements + LCM on external dependencies

• 7611a4f9 perf(cli|main): lazy loads config mangling, extract and enrich steps (#796)
• 2fea4985 perf(cli|report): lazy loads --init, reporter and caching code (#795)
• 44c34283 build(npm): updates external dependencies

See #794

👷 maintenance

• fb38030b build(npm): updates external dependencies
• 6277bed9 chore(ci): ensures ci is run on v12 branch as well

🔒 shasum of the package as published on npmjs: 748b8f9deeaef31b58db0f20edb5ffa1d19781f8

🐛 fixes

• 7d7d9e5e Replace "args" with "arguments" in config file template (#764) (thanks @greglockwood for spotting the bug and creating the PR!)

👷 maintenance

• f5384c06/ 62c1625a refactor(test): converts remaining tests for the cli from commonjs to esm (#766)

♻️ life cycle management

• 7270565e build(npm): update external dependencies
• e4eb94d9 ci(deps): bump actions/stale from 7 to 8 (#767)
• 8882780a build(npm): sync interpret version with webpack-cli & document source of the sync

🔏 sha-sum of the package as published on npmjs: 5ea774872831267c6870dc0d8472455c714ff098

✨ features

• 6ed9a0e4 feature(extract): adds support for TypeScript (>= 5) type only re-exports (#761)

👷 maintenance

• 1e6b25fb build(npm): update external dependencies
• 28041323 chore: regenerate the json schema's from corrected sources
• 9285246d chore: adds scheduled codeql static analysis

🔏 shasum of the package as published on npmjs: b5fdc3592938c7949c3667ab7758646964732bc4

👷 maintenance

• 441a348a fix: adds workaround for nodenext shenanigans with TypeScript (#757) (thanks @pbadenski for raising the issue & the clear feedback on it)
• 16356dee build(npm): update external dependencies
• 6b473888 fix: enables usage with TypeScript v5 (#760) (thanks to @lukeapage for both raising the issue and making a PR to fix it!)

🔏 shasum of the package as published on npmjs: 3de9c240b9a99c22828544d052cb266ad0c8abbe

📖 fixes

• cf61dbb8 fix: expands collapse patterns in --init template to include scoped packages (#756) (thanks @connorjs for the question, research and suggestion!)
• 73e63c9c doc(README): copy update in 'How do I use it?' section

👷 maintenance

• c2e64d1c build(npm): update external dependencies

🔒 sha-sum of the package as published on npmjs: 407f64aff22a236ca930749899da1c8e1dec0ec0

✨ features

• 4a2863b5 feature(cli): makes cli help output more focused (#752)
• 6e199c1c feature(cli): adds --no-metrics option (#751)
• 865af1be feature(cli): adds --no-ignore-known option (#750)
• baa21383 feature(cli): hides deprecated and implied options from --help output (#749)
• 1d0a7094 feature(cli): adds --no-config option (#747)

📖 documentation

• 59bea923 doc(README): updates install it section with instructions for yarn and pnpm (#748) (contribution by @cunzaizhuyi)
• 3a493bf3 doc(cli): copy edits

👷 maintenance

• c98dcb2b build(npm): update external dependencies

🔏 shasum of the package as published on npmjs: 688c57f69314c647239c592c7ea72c51948860fe

✨ features

• 3a47bd50 feature(init): adds mainFields derivation for TypeScript projects (#746)

🐛 fixes

• 2de94b81 bugfix(extract): uses tsc or swc for .mts & .cts as well (#745)

🔏 shasum of the package as released on npmjs: 3368ee96facf8f3d8cb68dcd821eb63e89dca5c6

✨ features

• 6198268d feature(resolve): enables passing mainFields & mainFiles to enhanced-resolve (#744)

👷 maintenance

• 5cf9b29e build(npm): update external dependencies

🔏 shasum of the package as published on npmjs: d373a31c4d3ab20b40b2dffe9467304281b03932

🐛 fixes

• d6e17f4f bugfix(resolve): in TypeScript resolve mjs, cjs to their ts variants as well (#742)

👷 maintenance

• e02784b5 chore(npm): removes unused run scripts from manifest (#740)
• 60cdaf9d chore(ci): moves lintstaged config from package.json to its own file (#739)
• 7f3b43f1 chore(lint): moves eslintignore from package.json into the .eslintrc (#738)
• 9dfa1dd7 chore(test): moves c8 cli parameters to .c8rc.json (#737)
• 909fc067 build(npm): update external dependencies (development dependencies only this time)

🔏 shasum of the package as published on npmjs: 01f2e7d573093a354024303d856b4b77395e7052