Issue: @import type not working

[louwers]

This creates a dependency:

import type * as t from "some-package";

This does not:

/** @import * as t from "some-package" */

Expected Behavior

I expect a (type) dependency to be created by the second form.

This syntax was introduced in TypeScript 5.5. https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#the-jsdoc-import-tag

Current Behavior

No dependency is created (even when tsPreCompilationDeps is true).

Possible Solution

Not sure. Could be an upstream (TypeScript) bug?

Steps to Reproduce (for bugs)

index.js

/** @import * as t from "./types.js" */

/** @returns {t.Boo} **/
function test() {
  return "bah";
}

types.ts

export type Boo = "bah";

package.json

{
  "name": "repro",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "description": "",
  "devDependencies": {
    "dependency-cruiser": "^16.6.0",
    "typescript": "^5.6.3"
  },
  "dependencies": {
    "left-pad": "^1.3.0"
  }
}

jsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "checkJs": true,
    "allowJs": true,
    "allowImportingTsExtensions": true,
    "noImplicitAny": true,
    "moduleResolution": "node",
    "module": "ES2022",
    "target": "ES2022"
  },
  "include": ["**/*.js"],
}

Run TypeScript, validate it works (try changing return):

npx tsc -p jsconfig.json 

Initialize depcruise (use current directory):

npx depcruise --init
# set tsPreCompilationDeps to true
npx depcruise . --output-type dot | dot -T svg > dependency-graph.svg

Context

I am trying to understand dependencies on types.

Your Environment

• Version used: 16.6.0
• Node version: 23
• Operating System and version: macOS 15
• Link to your project: https://github.com/louwers/reprodependencycruiser

[sverweij]

Hi @louwers - thanks for bringing this up!

At this time dependency-cruiser does not support annotations in comments like the ones that have been around for years (e.g. /** @type {import('thing').ISomeInterface} */, or flow annotations) or these new ones.

When I last looked at it (~5.5 years ago) the various parsers didn't emit them in their abstract syntax tree output in a structured fashion (i.e. text only) or didn't emit them at all (e.g. acorn, swc and the typescript-eslint parser strip all comments). That would mean I'd have to write a parser for it - or bring in another library (e.g. @ajaff/tsutils (whose author also contributed to dependency-cruiser) - or these days maybe ts-api-utils which seems to be its successor). Also, at that time typing-in-jsdoc was a niche use case as far as I could see - so I decided to put it aside and work on other things.

This might be different today: a quick check on today's MS typescript compiler output learns it emits something structured for jsdoc comments in its AST + some larger projects went the jsdoc-typing-in-js route, making it less of a niche feature.

... so I'll have a look again. I can't commit to a timeline a.t.m. though.

[louwers]

Ah I assumed some kind of API from TypeScript was used for parsing type dependencies.

some larger projects went the jsdoc-typing-in-js route, making it less of a niche feature

Yes and I it looks the TypeScript team changed their stance, facilitating the jsdoc-typing-in-js approach even more going forward:

"Our approach to JSDoc has evolved since this issue was created. (...) Typescript is the largest processor of JSDoc at this point, and TS users who want typing are probably the most prolific authors of it."

microsoft/TypeScript#27387 (comment)

... so I'll have a look again. I can't commit to a timeline a.t.m. though.

Cool. Thanks for the quick reply. Very neat project!

[sverweij]

@louwers I've published [email protected] a few minutes ago - it recognizes @import tags in jsdoc comments. As compared to the version you tested it takes one extra step: add the detectJSDocImports option in .dependency-cruiser.js, set it to true and Bob's your uncle.

I'll try and add support for the earlier 'bracket style' imports before releasing this with the latest tag on npmjs so we don't introduce a breaking change between two latest versions.

Thanks again for the very pro-active testing & feedback in the PR!

[louwers]

Thanks for implementing this, and nice to see you actually have a use for it too. 👍

[sverweij]

Dependency-cruiser recognizes both the @import style as well as the older 'bracket style' imports as of version 16.7.0 which just landed on npm.

release notes: https://github.com/sverweij/dependency-cruiser/releases/tag/v16.7.0