feat: show warning when engines mismatch (#51)

9romise · autofix-ci[bot] · web-flow · commit 5d44351c7ad9 · 2026-02-28T16:39:37.000+08:00
* feat: check mismatch engine

* refactor: use `Engines`

* refactor: unify `formatPackageId`

* [autofix.ci] apply automated fixes

* test: fix type

* update

* docs: update

---------

Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -46,6 +46,7 @@
 | `npmx.diagnostics.replacement`      | Show suggestions for package replacements                                               | `boolean` | `true`              |
 | `npmx.diagnostics.vulnerability`    | Show warnings for packages with known vulnerabilities                                   | `boolean` | `true`              |
 | `npmx.diagnostics.distTag`          | Show warnings when a dependency uses a dist tag                                         | `boolean` | `true`              |
+| `npmx.diagnostics.engineMismatch`   | Show warnings when dependency engines mismatch with the current package                 | `boolean` | `true`              |
 
 <!-- configs -->
 
diff --git a/package.json b/package.json
@@ -93,6 +93,11 @@
           "type": "boolean",
           "default": true,
           "description": "Show warnings when a dependency uses a dist tag"
+        },
+        "npmx.diagnostics.engineMismatch": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show warnings when dependency engines mismatch with the current package"
         }
       }
     },
diff --git a/playground/package.json b/playground/package.json
@@ -1,4 +1,7 @@
 {
+  "engines": {
+    "node": ">16"
+  },
   "dependencies": {
     "@deno/doc": "jsr:^0.189.1",
     "@prismicio/client": "~7.21.0-canary.147e3f2",
diff --git a/src/extractors/package-json.ts b/src/extractors/package-json.ts
@@ -1,4 +1,5 @@
 import type { DependencyInfo, Extractor } from '#types/extractor'
+import type { Engines } from 'fast-npm-meta'
 import type { Node } from 'jsonc-parser'
 import type { TextDocument } from 'vscode'
 import { isInRange } from '#utils/ast'
@@ -75,6 +76,25 @@ export class PackageJsonExtractor implements Extractor<Node> {
     return result
   }
 
+  getEngines(root: Node): Engines | undefined {
+    const enginesNode = findNodeAtLocation(root, ['engines'])
+    if (enginesNode?.type !== 'object' || !enginesNode.children?.length)
+      return
+
+    let engines: Engines | undefined
+
+    for (const engineNode of enginesNode.children) {
+      const [nameNode, rangeNode] = engineNode.children ?? []
+      if (typeof nameNode?.value !== 'string' || typeof rangeNode?.value !== 'string')
+        continue
+
+      engines ??= {}
+      engines[nameNode.value] = rangeNode.value
+    }
+
+    return engines
+  }
+
   getDependencyInfoByOffset(root: Node, offset: number) {
     const node = findNodeAtOffset(root, offset)
     if (!node || node.type !== 'string' || !this.isInDependencySection(root, node))
diff --git a/src/providers/diagnostics/index.ts b/src/providers/diagnostics/index.ts
@@ -1,6 +1,7 @@
 import type { DependencyInfo, ValidNode } from '#types/extractor'
 import type { PackageInfo } from '#utils/api/package'
 import type { ParsedVersion } from '#utils/version'
+import type { Engines } from 'fast-npm-meta'
 import type { Awaitable } from 'reactive-vscode'
 import type { Diagnostic, TextDocument } from 'vscode'
 import { useActiveExtractor } from '#composables/active-extractor'
@@ -14,6 +15,7 @@ import { languages } from 'vscode'
 import { displayName } from '../../generated-meta'
 import { checkDeprecation } from './rules/deprecation'
 import { checkDistTag } from './rules/dist-tag'
+import { checkEngineMismatch } from './rules/engine-mismatch'
 import { checkReplacement } from './rules/replacement'
 import { checkUpgrade } from './rules/upgrade'
 import { checkVulnerability } from './rules/vulnerability'
@@ -23,6 +25,7 @@ export interface DiagnosticContext {
   pkg: PackageInfo
   parsed: ParsedVersion | null
   exactVersion: string | null
+  engines: Engines | undefined
 }
 
 export interface NodeDiagnosticInfo extends Omit<Diagnostic, 'range' | 'source'> {
@@ -45,6 +48,8 @@ export function useDiagnostics() {
       rules.push(checkDeprecation)
     if (config.diagnostics.distTag)
       rules.push(checkDistTag)
+    if (config.diagnostics.engineMismatch)
+      rules.push(checkEngineMismatch)
     if (config.diagnostics.replacement)
       rules.push(checkReplacement)
     if (config.diagnostics.vulnerability)
@@ -83,6 +88,7 @@ export function useDiagnostics() {
     const targetVersion = document.version
 
     const dependencies = extractor.getDependenciesInfo(root)
+    const engines = extractor.getEngines?.(root)
     const diagnostics: Diagnostic[] = []
 
     for (const dep of dependencies) {
@@ -103,7 +109,7 @@ export function useDiagnostics() {
 
         for (const rule of rules) {
           try {
-            const diagnostic = await rule({ dep, pkg, parsed, exactVersion })
+            const diagnostic = await rule({ dep, pkg, parsed, exactVersion, engines })
             if (isDocumentChanged(document, targetUri, targetVersion))
               return
             if (!diagnostic)
diff --git a/src/providers/diagnostics/rules/deprecation.ts b/src/providers/diagnostics/rules/deprecation.ts
@@ -1,5 +1,6 @@
 import type { DiagnosticRule } from '..'
 import { npmxPackageUrl } from '#utils/links'
+import { formatPackageId } from '#utils/package'
 import { DiagnosticSeverity, DiagnosticTag, Uri } from 'vscode'
 
 export const checkDeprecation: DiagnosticRule = ({ dep, pkg, parsed, exactVersion }) => {
@@ -13,7 +14,7 @@ export const checkDeprecation: DiagnosticRule = ({ dep, pkg, parsed, exactVersio
 
   return {
     node: dep.versionNode,
-    message: `${dep.name} v${exactVersion} has been deprecated: ${versionInfo.deprecated}`,
+    message: `"${formatPackageId(dep.name, exactVersion)}" has been deprecated: ${versionInfo.deprecated}`,
     severity: DiagnosticSeverity.Error,
     code: {
       value: 'deprecation',
diff --git a/src/providers/diagnostics/rules/engine-mismatch.ts b/src/providers/diagnostics/rules/engine-mismatch.ts
@@ -0,0 +1,74 @@
+import type { Engines } from 'fast-npm-meta'
+import type { DiagnosticRule } from '..'
+import { npmxPackageUrl } from '#utils/links'
+import { formatPackageId } from '#utils/package'
+import Range from 'semver/classes/range'
+import intersects from 'semver/ranges/intersects'
+import subset from 'semver/ranges/subset'
+import { DiagnosticSeverity, Uri } from 'vscode'
+
+interface EngineMismatch {
+  engine: string
+  packageRange: string
+  dependencyRange: string
+  hasIntersection: boolean
+}
+
+function resolveEngineMismatches(
+  packageEngines: Engines,
+  dependencyEngines: Engines,
+) {
+  const mismatches: EngineMismatch[] = []
+
+  for (const [engine, dependencyRangeStr] of Object.entries(dependencyEngines)) {
+    const packageRangeStr = packageEngines[engine]
+    if (!packageRangeStr || !dependencyRangeStr)
+      continue
+
+    try {
+      const pkgRange = new Range(packageRangeStr)
+      const depRange = new Range(dependencyRangeStr)
+
+      if (subset(pkgRange, depRange))
+        continue
+
+      mismatches.push({
+        engine,
+        packageRange: packageRangeStr,
+        dependencyRange: dependencyRangeStr,
+        hasIntersection: intersects(pkgRange, depRange),
+      })
+    } catch {
+      continue
+    }
+  }
+
+  return mismatches
+}
+
+export const checkEngineMismatch: DiagnosticRule = ({ dep, pkg, parsed, exactVersion, engines }) => {
+  if (!parsed || !exactVersion || !engines)
+    return
+
+  const dependencyEngines = pkg.versionsMeta[exactVersion]?.engines
+  if (!dependencyEngines)
+    return
+
+  const mismatches = resolveEngineMismatches(engines, dependencyEngines)
+  if (mismatches.length === 0)
+    return
+
+  const mismatchDetails = mismatches
+    .map((mismatch) => `${mismatch.engine}: requires "${mismatch.dependencyRange}", but package supports "${mismatch.packageRange}"${mismatch.hasIntersection ? ' (partial overlap)' : ''}`)
+    .join('; ')
+
+  return {
+    node: dep.versionNode,
+    message: `Engines mismatch for "${formatPackageId(dep.name, exactVersion)}": ${mismatchDetails}.`,
+    severity: DiagnosticSeverity.Warning,
+    code: {
+      value: 'engine-mismatch',
+      target: Uri.parse(npmxPackageUrl(dep.name, parsed.version)),
+    },
+  }
+}
diff --git a/src/types/extractor.ts b/src/types/extractor.ts
@@ -1,3 +1,4 @@
+import type { Engines } from 'fast-npm-meta'
 import type { Node as JsonNode } from 'jsonc-parser'
 import type { Range, TextDocument } from 'vscode'
 import type { Node as YamlNode } from 'yaml'
@@ -19,4 +20,6 @@ export interface Extractor<T extends ValidNode = any> {
   getDependenciesInfo: (root: T) => DependencyInfo<T>[]
 
   getDependencyInfoByOffset: (root: T, offset: number) => DependencyInfo<T> | undefined
+
+  getEngines?: (root: T) => Engines | undefined
 }
diff --git a/src/utils/package.ts b/src/utils/package.ts
@@ -12,6 +12,10 @@ export function encodePackageName(name: string): string {
   return encodeURIComponent(name)
 }
 
+export function formatPackageId(name: string, version: string): string {
+  return `${name}@${version}`
+}
+
 export function resolveExactVersion(pkg: PackageInfo, version: string) {
   if (Object.hasOwn(pkg.distTags, version))
     return pkg.distTags[version]
diff --git a/tests/diagnostics/context.ts b/tests/diagnostics/context.ts
@@ -1,5 +1,6 @@
 import type { DependencyInfo } from '#types/extractor'
 import type { PackageInfo } from '#utils/api/package'
+import type { Engines } from 'fast-npm-meta'
 import type { DiagnosticContext } from '../../src/providers/diagnostics'
 import { resolveExactVersion } from '#utils/package'
 import { isSupportedProtocol, parseVersion } from '#utils/version'
@@ -8,16 +9,20 @@ interface CreateContextOptions {
   name: string
   version: string
   distTags?: Record<string, string>
-  versionsMeta?: Record<string, { deprecated?: string }>
+  versionsMeta?: Record<string, {
+    deprecated?: string
+    engines?: Engines
+  }>
+  engines?: Engines
 }
 
 export function createContext(options: CreateContextOptions): DiagnosticContext {
-  const { name, version, distTags = {}, versionsMeta = {} } = options
+  const { name, version, distTags = {}, versionsMeta = {}, engines } = options
   const dep: DependencyInfo = { name, version, nameNode: {}, versionNode: {} }
   const pkg = { distTags, versionsMeta, versionToTag: new Map() } as PackageInfo
   const parsed = parseVersion(version)
   const exactVersion = parsed && isSupportedProtocol(parsed.protocol)
     ? resolveExactVersion(pkg, parsed.version)
     : null
-  return { dep, pkg, parsed, exactVersion }
+  return { dep, pkg, parsed, exactVersion, engines }
 }
diff --git a/tests/diagnostics/deprecation.test.ts b/tests/diagnostics/deprecation.test.ts
@@ -9,10 +9,10 @@ function createDeprecationContext(version: string) {
     distTags: { latest: '2.0.0' },
     versionsMeta: {
       '1.0.0': {
-        deprecated: '1.0.0',
+        deprecated: 'old notice',
       },
       '1.2.0': {
-        deprecated: '1.2.0',
+        deprecated: 'new notice',
       },
       '2.0.0': {},
     },
@@ -25,7 +25,7 @@ describe('checkDeprecation', () => {
     const result = await checkDeprecation(ctx)
 
     expect(result).toBeDefined()
-    expect(result!.message).toMatchInlineSnapshot('"lodash v1.0.0 has been deprecated: 1.0.0"')
+    expect(result!.message).toMatchInlineSnapshot('""lodash@1.0.0" has been deprecated: old notice"')
     expect(result!.code).toMatchObject({ value: 'deprecation' })
   })
 
@@ -34,7 +34,7 @@ describe('checkDeprecation', () => {
     const result = await checkDeprecation(ctx)
 
     expect(result).toBeDefined()
-    expect(result!.message).toMatchInlineSnapshot('"lodash v1.2.0 has been deprecated: 1.2.0"')
+    expect(result!.message).toMatchInlineSnapshot('""lodash@1.2.0" has been deprecated: new notice"')
     expect(result!.code).toMatchObject({ value: 'deprecation' })
   })
 
diff --git a/tests/diagnostics/engine-mismatch.test.ts b/tests/diagnostics/engine-mismatch.test.ts
@@ -0,0 +1,89 @@
+import type { Engines } from 'fast-npm-meta'
+import { describe, expect, it } from 'vitest'
+import { checkEngineMismatch } from '../../src/providers/diagnostics/rules/engine-mismatch'
+import { createContext } from './context'
+
+function createEngineMismatchContext(
+  engines: Engines | undefined,
+  dependencyEngines: Engines | undefined,
+) {
+  return createContext({
+    name: 'foo',
+    version: '^1.0.0',
+    distTags: { latest: '1.0.0' },
+    versionsMeta: {
+      '1.0.0': dependencyEngines ? { engines: dependencyEngines } : {},
+    },
+    engines,
+  })
+}
+
+describe('checkEngineMismatch', () => {
+  it('should flag when engine ranges do not overlap', async () => {
+    const ctx = createEngineMismatchContext(
+      { node: '^18.0.0' },
+      { node: '>=20' },
+    )
+    const result = await checkEngineMismatch(ctx)
+
+    expect(result).toBeDefined()
+    expect(result!.code).toMatchObject({ value: 'engine-mismatch' })
+    expect(result!.message).toContain('requires ">=20", but package supports "^18.0.0"')
+  })
+
+  it('should flag when engine ranges overlap but are not fully compatible', async () => {
+    const ctx = createEngineMismatchContext(
+      { node: '>=20', npm: '>=8 <11' },
+      { node: '>=18', npm: '>=10 <12' },
+    )
+    const result = await checkEngineMismatch(ctx)
+
+    expect(result).toBeDefined()
+    expect(result!.message).toContain('npm')
+    expect(result!.message).toContain('partial overlap')
+  })
+
+  it('should include multiple engine mismatches in one diagnostic', async () => {
+    const ctx = createEngineMismatchContext(
+      { node: '^18.0.0', npm: '^9.0.0' },
+      { node: '>=20', npm: '>=10' },
+    )
+    const result = await checkEngineMismatch(ctx)
+
+    expect(result).toBeDefined()
+    expect(result!.message).toContain('node')
+    expect(result!.message).toContain('npm')
+  })
+
+  it('should not flag when package ranges are compatible', async () => {
+    const ctx = createEngineMismatchContext(
+      { node: '>=20', npm: '>=10' },
+      { node: '>=18', npm: '>=10' },
+    )
+
+    expect(await checkEngineMismatch(ctx)).toBeUndefined()
+  })
+
+  it('should not flag when package does not declare the dependency engine', async () => {
+    const ctx = createEngineMismatchContext(
+      { node: '>=20' },
+      { npm: '>=10' },
+    )
+
+    expect(await checkEngineMismatch(ctx)).toBeUndefined()
+  })
+
+  it('should not flag when either engines is missing', async () => {
+    expect(await checkEngineMismatch(createEngineMismatchContext(undefined, { node: '>=18' }))).toBeUndefined()
+    expect(await checkEngineMismatch(createEngineMismatchContext({ node: '>=18' }, undefined))).toBeUndefined()
+  })
+
+  it('should skip engines with non-standard semver values', async () => {
+    const ctx = createEngineMismatchContext(
+      { node: '>=18' },
+      { node: 'lts' },
+    )
+
+    expect(await checkEngineMismatch(ctx)).toBeUndefined()
+  })
+})

Original file line number	Diff line number	Diff line change
`@@ -93,6 +93,11 @@`
`93`	`93`	`"type": "boolean",`
`94`	`94`	`"default": true,`
`95`	`95`	`"description": "Show warnings when a dependency uses a dist tag"`
	`96`	`+ },`
	`97`	`+ "npmx.diagnostics.engineMismatch": {`
	`98`	`+ "type": "boolean",`
	`99`	`+ "default": true,`
	`100`	`+ "description": "Show warnings when dependency engines mismatch with the current package"`
`96`	`101`	`}`
`97`	`102`	`}`
`98`	`103`	`},`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,7 @@`
`1`	`1`	`{`
	`2`	`+ "engines": {`
	`3`	`+ "node": ">16"`
	`4`	`+ },`
`2`	`5`	`"dependencies": {`
`3`	`6`	`"@deno/doc": "jsr:^0.189.1",`
`4`	`7`	`"@prismicio/client": "~7.21.0-canary.147e3f2",`