feat: add strategies option for detect API (#42)

Co-authored-by: Anthony Fu <github@antfu.me>

Author: bluwy

.gitignore

@@ -83,3 +83,6 @@ _storage.json
 
 # System files
 .DS_Store
+
+# Allow node_modules in install-metadata fixture to test installation setups
+!test/fixtures/install-metadata/*/node_modules

README.md

@@ -5,9 +5,9 @@
 [![JSDocs][jsdocs-src]][jsdocs-href]
 [![License][license-src]][license-href]
 
-Package manager detector is based on lock files and the `packageManager` field in the current project's `package.json` file.
+Package manager detector is based on lock files, the `package.json` `packageManager` field, and installation metadata to detect the package manager used in a project.
 
-It will detect your `yarn.lock` / `pnpm-lock.yaml` / `package-lock.json` / `bun.lock` / `bun.lockb` / `deno.lock` to know the current package manager and use the `packageManager` field in your `package.json` if present.
+It supports `npm`, `yarn`, `pnpm`, `deno`, and `bun`.
 
 ## Install
 

src/constants.ts

@@ -21,6 +21,19 @@ export const LOCKS: Record<string, AgentName> = {
   'npm-shrinkwrap.json': 'npm',
 }
 
+// the order here matters, more specific one comes first
+export const INSTALL_METADATA: Record<string, AgentName> = {
+  'node_modules/.deno/': 'deno',
+  'node_modules/.pnpm/': 'pnpm',
+  'node_modules/.yarn-state.yml': 'yarn', // yarn v2+ (node-modules)
+  'node_modules/.yarn_integrity': 'yarn', // yarn v1
+  'node_modules/.package-lock.json': 'npm',
+  '.pnp.cjs': 'yarn', // yarn v3+ (pnp)
+  '.pnp.js': 'yarn', // yarn v2 (pnp)
+  'bun.lock': 'bun',
+  'bun.lockb': 'bun',
+}
+
 export const INSTALL_PAGE: Record<Agent, string> = {
   'bun': 'https://bun.sh',
   'deno': 'https://deno.com',

src/detect.ts

@@ -2,11 +2,12 @@ import type { Agent, AgentName, DetectOptions, DetectResult } from './types'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
-import { AGENTS, LOCKS } from './constants'
+import { AGENTS, INSTALL_METADATA, LOCKS } from './constants'
 
-async function isFile(path: string) {
+function pathExists(path: string, type: 'file' | 'dir') {
   try {
-    return (await fs.promises.stat(path)).isFile()
+    const stat = fs.statSync(path)
+    return type === 'file' ? stat.isFile() : stat.isDirectory()
   }
   catch {
     return false
@@ -39,8 +40,11 @@ function* lookup(cwd: string = process.cwd()): Generator<string> {
   }
 }
 
-async function parsePackageJson(filepath: string, onUnknown: DetectOptions['onUnknown']): Promise<DetectResult | null> {
-  return (!filepath || !await isFile(filepath))
+async function parsePackageJson(
+  filepath: string,
+  onUnknown: DetectOptions['onUnknown'],
+): Promise<DetectResult | null> {
+  return (!filepath || !pathExists(filepath, 'file'))
     ? null
     : await handlePackageManager(filepath, onUnknown)
 }
@@ -51,24 +55,48 @@ async function parsePackageJson(filepath: string, onUnknown: DetectOptions['onUn
  * @returns {Promise<DetectResult | null>} The detected package manager or `null` if not found.
  */
 export async function detect(options: DetectOptions = {}): Promise<DetectResult | null> {
-  const { cwd, onUnknown } = options
+  const { cwd, strategies = ['lockfile', 'packageManager-field'], onUnknown } = options
 
   for (const directory of lookup(cwd)) {
-    // Look up for lock files
-    for (const lock of Object.keys(LOCKS)) {
-      if (await isFile(path.join(directory, lock))) {
-        const name = LOCKS[lock]
-        const result = await parsePackageJson(path.join(directory, 'package.json'), onUnknown)
-        if (result)
-          return result
-        else
-          return { name, agent: name }
+    for (const strategy of strategies) {
+      switch (strategy) {
+        case 'lockfile': {
+          // Look up for lock files
+          for (const lock of Object.keys(LOCKS)) {
+            if (await pathExists(path.join(directory, lock), 'file')) {
+              const name = LOCKS[lock]
+              const result = await parsePackageJson(path.join(directory, 'package.json'), onUnknown)
+              if (result)
+                return result
+              else
+                return { name, agent: name }
+            }
+          }
+          break
+        }
+        case 'packageManager-field': {
+          // Look up for package.json
+          const result = await parsePackageJson(path.join(directory, 'package.json'), onUnknown)
+          if (result)
+            return result
+          break
+        }
+        case 'install-metadata': {
+          // Look up for installation metadata files
+          for (const metadata of Object.keys(INSTALL_METADATA)) {
+            const fileOrDir = metadata.endsWith('/') ? 'dir' : 'file'
+            if (await pathExists(path.join(directory, metadata), fileOrDir)) {
+              const name = INSTALL_METADATA[metadata]
+              const agent = name === 'yarn'
+                ? isMetadataYarnClassic(metadata) ? 'yarn' : 'yarn@berry'
+                : name
+              return { name, agent }
+            }
+          }
+          break
+        }
       }
     }
-    // Look up for package.json
-    const result = await parsePackageJson(path.join(directory, 'package.json'), onUnknown)
-    if (result)
-      return result
   }
 
   return null
@@ -107,3 +135,7 @@ async function handlePackageManager(
   catch {}
   return null
 }
+
+function isMetadataYarnClassic(metadataPath: string) {
+  return metadataPath.endsWith('.yarn_integrity')
+}

src/types.ts

@@ -31,12 +31,26 @@ export interface ResolvedCommand {
   args: string[]
 }
 
+export type DetectStrategy = 'lockfile' | 'packageManager-field' | 'install-metadata'
+
 export interface DetectOptions {
   /**
    * Current working directory to start looking up for package manager.
    * @default `process.cwd()`
    */
   cwd?: string
+  /**
+   * The strategies to use for detecting the package manager. The strategies
+   * are executed in the order it's specified for every directory that it iterates
+   * upwards from the `cwd`.
+   *
+   * - `lockfile`: Look up for lock files.
+   * - `packageManager-field`: Look up for the `packageManager` field in package.json.
+   * - `install-metadata`: Look up for installation metadata added by package managers.
+   *
+   * @default ['lockfile', 'packageManager-field']
+   */
+  strategies?: DetectStrategy[]
   /**
    * Callback when unknown package manager from package.json.
    * @param packageManager - The `packageManager` value from package.json file.

test/__snapshots__/detect.spec.ts.snap

@@ -1,5 +1,63 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`install-metadata > bun 1`] = `
+{
+  "agent": "bun",
+  "name": "bun",
+}
+`;
+
+exports[`install-metadata > deno 1`] = `
+{
+  "agent": "deno",
+  "name": "deno",
+}
+`;
+
+exports[`install-metadata > npm 1`] = `
+{
+  "agent": "npm",
+  "name": "npm",
+}
+`;
+
+exports[`install-metadata > pnpm 1`] = `
+{
+  "agent": "pnpm",
+  "name": "pnpm",
+}
+`;
+
+exports[`install-metadata > unknown 1`] = `null`;
+
+exports[`install-metadata > yarn 1`] = `
+{
+  "agent": "yarn",
+  "name": "yarn",
+}
+`;
+
+exports[`install-metadata > yarn@berry 1`] = `
+{
+  "agent": "yarn@berry",
+  "name": "yarn",
+}
+`;
+
+exports[`install-metadata > yarn@berry_pnp-v2 1`] = `
+{
+  "agent": "yarn@berry",
+  "name": "yarn",
+}
+`;
+
+exports[`install-metadata > yarn@berry_pnp-v3 1`] = `
+{
+  "agent": "yarn@berry",
+  "name": "yarn",
+}
+`;
+
 exports[`lockfile > bun 1`] = `
 {
   "agent": "bun",
@@ -91,6 +149,14 @@ exports[`packager > pnpm@6 1`] = `
 }
 `;
 
+exports[`packager > pnpm-version-range 1`] = `
+{
+  "agent": "pnpm",
+  "name": "pnpm",
+  "version": "8.0.0",
+}
+`;
+
 exports[`packager > unknown 1`] = `null`;
 
 exports[`packager > yarn 1`] = `

test/detect.spec.ts

@@ -1,19 +1,20 @@
 import type { MockInstance } from 'vitest'
+import type { DetectOptions } from '../src'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import fs from 'fs-extra'
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
-import { AGENTS, detect } from '../src'
+import { detect } from '../src'
 
 let basicLog: MockInstance, errorLog: MockInstance, warnLog: MockInstance, infoLog: MockInstance
 
-function detectTest(fixture: string, agent: string) {
+function detectTest(fixture: string, agent: string, options?: DetectOptions) {
   return async () => {
     const cwd = await fs.mkdtemp(path.join(tmpdir(), 'ni-'))
     const dir = path.join(__dirname, 'fixtures', fixture, agent)
     await fs.copy(dir, cwd)
 
-    expect(await detect({ cwd })).toMatchSnapshot()
+    expect(await detect({ cwd, ...options })).toMatchSnapshot()
   }
 }
 
@@ -28,17 +29,29 @@ afterAll(() => {
   vi.resetAllMocks()
 })
 
-const agents = [...AGENTS, 'unknown']
-const fixtures = ['lockfile', 'packager']
+const fixtures = ['lockfile', 'packager', 'install-metadata']
 
-// matrix testing of: fixtures x agents
-fixtures.forEach(fixture => describe(fixture, () => agents.forEach((agent) => {
-  it(agent, detectTest(fixture, agent))
+fixtures.forEach(fixture => describe(fixture, () => {
+  const fixtureDirs = getFixtureDirs(fixture)
+
+  fixtureDirs.forEach((dir) => {
+    let options: DetectOptions | undefined
+    if (fixture === 'install-metadata') {
+      options = { strategies: ['install-metadata', 'lockfile', 'packageManager-field'] }
+    }
+    it(dir, detectTest(fixture, dir, options))
+  })
 
   it('no logs', () => {
     expect(basicLog).not.toHaveBeenCalled()
     expect(warnLog).not.toHaveBeenCalled()
     expect(errorLog).not.toHaveBeenCalled()
     expect(infoLog).not.toHaveBeenCalled()
   })
-})))
+}))
+
+function getFixtureDirs(fixture: string) {
+  const fixtureDir = path.join(__dirname, 'fixtures', fixture)
+  const items = fs.readdirSync(fixtureDir)
+  return items.filter(item => fs.statSync(path.join(fixtureDir, item)).isDirectory())
+}

test/exports.test.ts

@@ -12,6 +12,7 @@ it('exports-snapshot', async () => {
       ".": {
         "AGENTS": "object",
         "COMMANDS": "object",
+        "INSTALL_METADATA": "object",
         "INSTALL_PAGE": "object",
         "LOCKS": "object",
         "constructCommand": "function",
@@ -26,6 +27,7 @@ it('exports-snapshot', async () => {
       },
       "./constants": {
         "AGENTS": "object",
+        "INSTALL_METADATA": "object",
         "INSTALL_PAGE": "object",
         "LOCKS": "object",
       },