Migrate from dependency-cruiser

The config of Oxcruise is much smaller than the config of dependency-cruiser. Oxcruise does not read .dependency-cruiser.* files in a check. The oxcruise --migrate command converts one and says what it could not convert.

Run the migration

npx oxcruise --migrate
npx oxcruise --migrate -c .oxcruiserc.json
npx oxcruise --migrate=config/.dependency-cruiser.cjs -c config/oxcruise.config.ts

• The first command reads .dependency-cruiser.json, .js, .cjs or .mjs. It writes oxcruise.config.ts.
• -c names the file to write. A .json name gives a JSON file.
• --migrate=FILE names the file to read.

--migrate never overwrites a file. When the target exists, the command stops with "already exists". Delete the file or choose another name with -c.

How the conversion works

The conversion is conservative:

• A path regex becomes a glob only when it has a common shape. See Regex to glob.
• Oxcruise drops a whole rule that uses a condition that it does not have, with a named warning. Dropping only the condition would make the rule broader than you wrote it.
• A regex that does not convert drops its rule, with a named warning.
• When the target is a TypeScript file, every warning is also in that file, as a // TODO: comment. A .json target has no comments, so the warnings go to stderr only.
• Oxcruise drops allowed and required sections with a warning.

What maps

Regex to glob

Other regexes do not convert. Examples are \d, [a-z], look-around and quantified groups. Oxcruise drops the rule or the entry and names the regex.

The recommended rules

Oxcruise has the rules of the recommended config of dependency-cruiser built in. It sorts them into categories, and the default level of a category applies. Two of the rules are off by default: optional-dependencies and peer-dependencies.

What behaves differently

• Globs, not regexes. The regex crate matches rules in linear time, so Oxcruise needs no guard for unsafe regexes. Globs have *, **, ?, [ab], {a,b} and {name} captures.
• One report for each cycle. Oxcruise reports a cycle once and, by default, only when it exists at runtime. A compiler erases import type.
• Ignore comments exist. See Inline ignore comments.
• Exit codes. Errors give 1. --deny-warnings with warnings, and --max-warnings N when exceeded, also give 1. A bad config gives 2. There is no --compat.
• Output formats. They are default, long, json, github, text and plugin reporters. The --visualize mode replaces dot, mermaid and archi: it writes an interactive site (see Visualize the graph). The json format of Oxcruise has a different shape from the json format of dependency-cruiser. A tool that reads the old output must read the new format. See Output formats.
• Dual packages. Oxcruise resolves them by import syntax, as Node.js does. See Differences.
• Merged syntax kinds. A file that both imports and re-exports one module has both kinds on that dependency.
• No TypeScript install. Oxcruise parses TS, TSX, MTS, CTS, JSX, Vue, Svelte and Astro itself.
• Always extracted. They are JSDoc imports, triple-slash directives, and new URL("./x", import.meta.url) and new Worker(new URL(...)).
• calls replaces exoticRequireStrings. The first string argument of the function is a dependency. It resolves as an ES import, unless the name of the function starts with require.
• AMD. Ids without a leading ./ resolve like package specifiers. Oxcruise does not read the requirejs baseUrl and paths config.

Check your migration

npx oxcruise --migrate -c .oxcruiserc.json
npx depcruise src -T json > before.json
npx oxcruise src -f json > after.json

Compare the modules and the dependencies in the two files. The tasks/conformance folder of the repository does this against dependency-cruiser 18.7. See Differences.