From f05d8e8147a9fce6cc841192ca95bbddb191ce7a Mon Sep 17 00:00:00 2001 From: sverweij Date: Sun, 24 Nov 2024 19:17:02 +0100 Subject: [PATCH] doc: updates FAQ, options-reference, rules-reference --- .dependency-cruiser.mjs | 1 + doc/faq.md | 18 +++++++++++-- doc/options-reference.md | 8 +++--- doc/rules-reference.md | 56 ++++++++++++++++++++-------------------- 4 files changed, 48 insertions(+), 35 deletions(-) diff --git a/.dependency-cruiser.mjs b/.dependency-cruiser.mjs index caa96fe77..9244b7d34 100644 --- a/.dependency-cruiser.mjs +++ b/.dependency-cruiser.mjs @@ -1,3 +1,4 @@ +/* eslint-disable max-lines */ import { fileURLToPath } from "node:url"; const defaultStrictRules = fileURLToPath( diff --git a/doc/faq.md b/doc/faq.md index 2f8e04d1e..9c5782a97 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -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. diff --git a/doc/options-reference.md b/doc/options-reference.md index 5cb4a2864..b61582771 100644 --- a/doc/options-reference.md +++ b/doc/options-reference.md @@ -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. diff --git a/doc/rules-reference.md b/doc/rules-reference.md index cfeb4775d..8263cb843 100644 --- a/doc/rules-reference.md +++ b/doc/rules-reference.md @@ -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 | `/// ` | -| triple-slash-directive | with a triple slash directive (oldskool TypeScript) | | -| triple-slash-file-reference | with a triple slash directive, specifically importing another module | `/// ` | -| triple-slash-type-reference | with a triple slash directive, specifically importing 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 | `/// ` | +| triple-slash-directive | with a triple slash directive (oldskool TypeScript) | | +| triple-slash-file-reference | with a triple slash directive, specifically importing another module | `/// ` | +| triple-slash-type-reference | with a triple slash directive, specifically importing 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`