Skip to content

Commit

Permalink
doc: updates FAQ, options-reference, rules-reference
Browse files Browse the repository at this point in the history
  • Loading branch information
@sverweij
sverweij committed Nov 24, 2024
1 parent c01204f commit f05d8e8
Show file tree
Hide file tree
Showing 4 changed files with 48 additions and 35 deletions.
1 change: 1 addition & 0 deletions .dependency-cruiser.mjs
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
/* eslint-disable max-lines */
import { fileURLToPath } from "node:url";

const defaultStrictRules = fileURLToPath(
Expand Down
18 changes: 16 additions & 2 deletions doc/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -576,10 +576,24 @@ _teamcity_ reporters (he _dot_ and _ddot_ reporters already did before).
**A**: From version 5.4.0 or higher you can add an _exoticRequireStrings_ key in
your configuration with the wrapper(s) and/ or re-definitions of require:
```json
"exoticRequireStrings": ["window.require", "need", "tryRequire"]
```javascript
exoticRequireStrings: ["window.require", "need", "tryRequire"];
```
### Q: I'm using jsdoc/ tsdoc comments to declare dependencies - how do I make sure dependency-cruiser picks those up?
**A** From version 16.7.0 you can add this to your configuration:
```javascript
//...
detectJSDocImports: true; // implies `parser: tsc`
// ...
```
As only the `tsc` TypeScript parser supports this, it will need `typescript`
to be installed (dependency-cruiser will automatically use it). For more
information see [detectJSDocImports in the options reference](./options-reference#detectjsdocimports-detect-dependencies-in-jsdoc-comments)
### Q: Can I get code completion for .dependency-cruiser.js?
**A**: Yes.
Expand Down
8 changes: 3 additions & 5 deletions doc/options-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -791,12 +791,10 @@ you can provide the parameters like so:
If you have dependencies in JSDoc comments that you want to take into account
you can set this option to `true`. This will make dependency-cruiser look at
TypeScript 5.5+ [`@import` tags](https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#the-jsdoc-import-tag).
TypeScript 5.5+ [`@import` tags](https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#the-jsdoc-import-tag) as well as to bracket style imports (e.g. `/** @type {import('./thing').SomeType} */`)
that have been part of TypeScript jsdoc/ tsdoc specification for a long time.

In the near future it will also look to bracket style imports (e.g. `/** @type {import('./thing').SomeType} */`)
in all JSDoc tags they can occur in (e.g. `@param`, `@returns`, `@type`, `@typedef` etc).

As currently on the TypeScript compiler (`tsc`) can detect these imports, switching
As currently only the TypeScript compiler (`tsc`) can detect these imports, switching
on this option implies dependency-cruiser will set `options.parser` to `tsc` so
it uses the TypeScript compiler to parse not only TypeScript but also JavaScript.

Expand Down
56 changes: 28 additions & 28 deletions doc/rules-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -984,34 +984,34 @@ the dependency was declared. One or more of these can occur at the same time. E.
dependency which resolves to a base url in a tsconfig.json you'll see `import`, `aliased` as well as
`aliased-tsconfig` and `aliased-tsconfig-base-url`.

| dependency type | meaning the module was imported ... | example |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| aliased | via an alias of some sort (e.g. tsconfig paths, subpath imports, npm workspace or webpack aliases) | "~/hello.ts" |
| aliased-subpath-import | via a [subpath import](https://nodejs.org/api/packages.html#subpath-imports) | "#thing/hello.mjs" |
| aliased-tsconfig | via a typescript compilerOptions.paths or compilerOptions.baseUrl setting in tsconfig. | "@thing/hello" |
| aliased-tsconfig-base-url | via a typescript [compilerOptions.baseUrl setting in tsconfig](https://www.typescriptlang.org/tsconfig#baseUrl) | "libs/utensils/src/hello.js" |
| aliased-tsconfig-paths | via a typescript [compilerOptions.paths setting in tsconfig](https://www.typescriptlang.org/tsconfig#paths) | "@thing/hello" |
| aliased-webpack | via a [webpack resolve alias](https://webpack.js.org/configuration/resolve/#resolvealias) | "Utilities" |
| aliased-workspace | via a [workspace](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#workspaces) | "local-workspace-package" |
| amd-define | with an AMD `define` wrapper (popularized by requirejs) | `define(["./thing"], function(thing){ /* do stuff */ })` |
| amd-exotic-require | with a require statement within an AMD module (but with the first parameter baring an insensible non-standard name) | `define(function(want, exports, module){ var one = want('./thing')})` |
| amd-require | with a require statement within an AMD module | `define(function(require, exports, module){ var one = require('./thing')})` |
| dynamic-import | with a dynamic import statement | `const { thing } = await import("./things")` |
| exotic-require | with a statement that isn't 'require' see [exoticallyRequired](#exoticallyrequired-exoticrequire-and-exoticrequirenot) | `const { thing } = want("./thing")` |
| export | implicitly via a module export | `export { thing } from "./things"` |
| import | with a 'regular' ES import | `import { thing } from "./things` |
| import-equals | with an 'import equals' statement | `import fs = require("fs")` |
| jsdoc | in jsdoc. See `jsdoc-bracket-import` and `jsdoc-import-tag`. Needs [detectJSDocImports](options-reference.md#detectjsdocimports-detect-dependencies-in-jsdoc-comments) set to `true` | `/** @type {import('./things').thing} */`, `/** @import { thing } from "things" */` |
| jsdoc-bracket-import | in a jsdoc comment with a 'bracket' style import. Always `type-only`, also has the `jsdoc` dependency type. FUTURE FEATURE | `/** @type {import('./things').thing} */` |
| jsdoc-import-tag | in a jsdoc comment with an @import tag. Always `type-only`, also has the `jsdoc` dependency type. | `/** @import { thing } from "things" */` |
| pre-compilation-only | but the dependency will disappear at runtime. See [preCompilationOnly](#preCompilationOnly) | `import { thing } from "./things"` // and continue to not use `thing` |
| require | with a commonjs 'require' statement | `const memoize = require("lodash/memoize")` |
| triple-slash-amd-dependency | with a triple slash directive, specifically declaring an AMD dependency | `/// <amd-dependency path="./ts-thing-types" />` |
| triple-slash-directive | with a triple slash directive (oldskool TypeScript) | |
| triple-slash-file-reference | with a triple slash directive, specifically importing another module | `/// <reference path="./ts-thing" />` |
| triple-slash-type-reference | with a triple slash directive, specifically importing types | `/// <reference types="./ts-thing-types" />` |
| type-import | as part of a type declaration | `const lAThing: import('./things').IThing = {}` |
| type-only | as 'type only' - only available for TypeScript sources, only for tsPreCompilationDeps !== false. | `import type { IThing } from "./things"` |
| dependency type | meaning the module was imported ... | example |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| aliased | via an alias of some sort (e.g. tsconfig paths, subpath imports, npm workspace or webpack aliases) | "~/hello.ts" |
| aliased-subpath-import | via a [subpath import](https://nodejs.org/api/packages.html#subpath-imports) | "#thing/hello.mjs" |
| aliased-tsconfig | via a typescript compilerOptions.paths or compilerOptions.baseUrl setting in tsconfig. | "@thing/hello" |
| aliased-tsconfig-base-url | via a typescript [compilerOptions.baseUrl setting in tsconfig](https://www.typescriptlang.org/tsconfig#baseUrl) | "libs/utensils/src/hello.js" |
| aliased-tsconfig-paths | via a typescript [compilerOptions.paths setting in tsconfig](https://www.typescriptlang.org/tsconfig#paths) | "@thing/hello" |
| aliased-webpack | via a [webpack resolve alias](https://webpack.js.org/configuration/resolve/#resolvealias) | "Utilities" |
| aliased-workspace | via a [workspace](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#workspaces) | "local-workspace-package" |
| amd-define | with an AMD `define` wrapper (popularized by requirejs) | `define(["./thing"], function(thing){ /* do stuff */ })` |
| amd-exotic-require | with a require statement within an AMD module (but with the first parameter baring an insensible non-standard name) | `define(function(want, exports, module){ var one = want('./thing')})` |
| amd-require | with a require statement within an AMD module | `define(function(require, exports, module){ var one = require('./thing')})` |
| dynamic-import | with a dynamic import statement | `const { thing } = await import("./things")` |
| exotic-require | with a statement that isn't 'require' see [exoticallyRequired](#exoticallyrequired-exoticrequire-and-exoticrequirenot) | `const { thing } = want("./thing")` |
| export | implicitly via a module export | `export { thing } from "./things"` |
| import | with a 'regular' ES import | `import { thing } from "./things` |
| import-equals | with an 'import equals' statement | `import fs = require("fs")` |
| jsdoc | in jsdoc. See `jsdoc-bracket-import` & `jsdoc-import-tag`. Needs [detectJSDocImports](options-reference.md#detectjsdocimports-detect-dependencies-in-jsdoc-comments) set to `true` | `/** @type {import('./things').thing} */`, `/** @import { thing } from "things" */` |
| jsdoc-bracket-import | in jsdoc with a 'bracket' style import. Always `type-only`, also has the `jsdoc` dependency type. | `/** @type {import('./things').thing} */` |
| jsdoc-import-tag | in jsdoc with an @import tag. Always `type-only`, also has the `jsdoc` dependency type. | `/** @import { thing } from "things" */` |
| pre-compilation-only | but the dependency will disappear at runtime. See [preCompilationOnly](#preCompilationOnly) | `import { thing } from "./things"` // and continue to not use `thing` |
| require | with a commonjs 'require' statement | `const memoize = require("lodash/memoize")` |
| triple-slash-amd-dependency | with a triple slash directive, specifically declaring an AMD dependency | `/// <amd-dependency path="./ts-thing-types" />` |
| triple-slash-directive | with a triple slash directive (oldskool TypeScript) | |
| triple-slash-file-reference | with a triple slash directive, specifically importing another module | `/// <reference path="./ts-thing" />` |
| triple-slash-type-reference | with a triple slash directive, specifically importing types | `/// <reference types="./ts-thing-types" />` |
| type-import | as part of a type declaration | `const lAThing: import('./things').IThing = {}` |
| type-only | as 'type only' - only available for TypeScript sources, only for tsPreCompilationDeps !== false. | `import type { IThing } from "./things"` |

### `dynamic`

Expand Down

0 comments on commit f05d8e8

Please sign in to comment.