npq 3.8.0 → 3.9.0

package/.github/workflows/main.yml

@@ -7,7 +7,7 @@ jobs:
     strategy:
       matrix:
         platform: [ubuntu-latest]
-        node: ['18', '20']
+        node: ['20', '22', '24']
     name: Node ${{ matrix.node }} (${{ matrix.platform }})
     runs-on: ${{ matrix.platform }}
     steps:
@@ -48,7 +48,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
-          node-version: '20'
+          node-version: '24'
       - name: install dependencies
         run: npm ci --ignore-engines --ignore-scripts
       - name: release

package/README.md

@@ -1,9 +1,5 @@
-<p align="center">
-	<br>
-  <img width="200" src="https://github.com/lirantal/npq/raw/main/.github/Logo%20Horizontal.png">
-	<br>
-	safely* install packages with npm/yarn by auditing them as part of your install process
-</p>
+npq allows you to audit npm packages _before_ you install them
+
 
 [![npm](https://img.shields.io/npm/v/npq.svg)](https://www.npmjs.com/package/npq)
 [![npm](https://img.shields.io/npm/l/npq.svg)](https://www.npmjs.com/package/npq)
@@ -12,8 +8,7 @@
 [![Known Vulnerabilities](https://snyk.io/test/github/lirantal/npq/badge.svg)](https://snyk.io/test/github/lirantal/npq)
 [![Security Responsible Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg)](./SECURITY.md)
 
-![npq-demo-3-final](https://github.com/lirantal/npq/blob/main/.github/npq-demo-1.gif?raw=true)
-
+![npq demo screenshot](https://github.com/user-attachments/assets/a201d041-2ce2-4e2d-b066-1395078a83e3)
 
 Media coverage about npq:
 - As mentioned on [Thomas Gentilhomme](https://github.com/fraxken)'s French book of [Become a Node.js Developer](https://docs.google.com/document/d/1JHgmEFkc8Py4XSuCB8_DQ5FFEJoogyeninFK6ucTd4o/edit#) 
@@ -44,7 +39,11 @@ npq install express
 
 If npq is prompted to continue with the install, it simply hands over the actual package install job to the package manager (npm by default).
 
-safely* - there's no guaranteed safety; a malicious or vulnerable package could still exist that has no security vulnerabilities publicly disclosed and passes npq's checks.
+DISCLAIMER: there's no guaranteed absolute safety; a malicious or vulnerable package could still exist that has no security vulnerabilities publicly disclosed and passes npq's checks.
+
+## Demo
+
+https://github.com/user-attachments/assets/619ab3f6-aa3f-483c-9560-0f18e033e6bf
 
 ## Install
 
@@ -99,6 +98,9 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | provenance | Will verify the package's attestations of provenance metadata for the published package
 | version-maturity | Will show a warning if the specific version being installed was published less than 7 days ago | Helps identify recently published versions that may not have been reviewed by the community yet
 | newBin | Will show a warning if the package version being installed introduces a new command-line binary (via the `bin` field in `package.json`) that was not present in its previous version. | Helps identify potentially unexpected new executables being added to your `node_modules/.bin/` directory.
+| typosquatting | Will show a warning if the package name is similar to a popular package name, which could indicate a potential typosquatting attack. | Helps identify packages that may be trying to trick users into installing them by mimicking popular package names.
+| deprecation | Will show a warning if the package version being installed is deprecated. | Helps identify packages that are no longer maintained or recommended for use.
+
 
 ### Disabling Marshalls
 
@@ -129,6 +131,7 @@ Here are all the available environment variable names for disabling specific mar
 | typosquatting | `MARSHALL_DISABLE_TYPOSQUATTING` | Disable typosquatting detection |
 | version-maturity | `MARSHALL_DISABLE_VERSION_MATURITY` | Disable version maturity checks |
 | newBin | `MARSHALL_DISABLE_NEWBIN` | Disable new binary introduction checks |
+| deprecation | `MARSHALL_DISABLE_DEPRECATION` | Disable deprecation checks |
 
 ### Run checks on package without installing it:
 
@@ -136,6 +139,12 @@ Here are all the available environment variable names for disabling specific mar
 npq install express --dry-run
 ```
 
+### Force non-rich text output:
+
+```sh
+npq install express --plain
+```
+
 ## Learn Node.js Security
 
 <div align="center">

package/__tests__/__fixtures__/test.marshall.js

@@ -22,25 +22,24 @@ class TestMarshall extends BaseMarshall {
     return Promise.all(tasks)
   }
 
-  mockCheck(pkg, ctx, task) {
+  mockCheck(pkg, ctx) {
     return this.validateSomething(pkg)
       .then(() => {
         const data = 'mock data check'
-        task.output = `querying ${pkg}...`
-        ctx.marshalls[this.name].data[pkg] = data
+        ctx.marshalls[this.name].data[pkg.packageName] = data
 
         return data
       })
       .catch((err) => {
         this.setMessage({
-          pkg,
+          pkg: pkg.packageName,
           message: err.message
         })
       })
   }
 
   validateSomething(pkg) {
-    if (pkg === 'express' || pkg === 'semver') {
+    if (pkg.packageName === 'express' || pkg.packageName === 'semver') {
       return Promise.resolve()
     } else {
       return Promise.reject(new Error('simulating mock error'))
@@ -48,7 +47,7 @@ class TestMarshall extends BaseMarshall {
   }
 
   validate(pkg) {
-    if (pkg === 'express' || pkg === 'semver') {
+    if (pkg.packageName === 'express' || pkg.packageName === 'semver') {
       return Promise.resolve('validation-result')
     } else {
       return Promise.reject(new Error('simulating mock error'))

package/__tests__/cli.test.js

@@ -0,0 +1,110 @@
+// __tests__/cli.test.js
+
+// Mock dependencies. These are hoisted by Jest.
+jest.mock('../lib/cli', () => ({
+  CliParser: {
+    parseArgsFull: jest.fn(),
+    exit: jest.fn()
+  }
+}))
+jest.mock('../lib/helpers/cliSupportHandler', () => ({
+  isEnvSupport: jest.fn().mockReturnValue(true),
+  isInteractiveTerminal: jest.fn(),
+  noSupportError: jest.fn()
+}))
+
+// Create a shared mock for the spinner instance that we can inspect in tests.
+const mockSpinnerInstance = {
+  start: jest.fn(),
+  stop: jest.fn()
+}
+jest.mock('../lib/helpers/cliSpinner', () => ({
+  // The Spinner property is a mock constructor that returns our shared mock instance.
+  Spinner: jest.fn().mockImplementation(() => mockSpinnerInstance)
+}))
+
+jest.mock('../lib/helpers/sourcePackages', () => ({
+  getProjectPackages: jest.fn().mockResolvedValue(['express'])
+}))
+jest.mock('../lib/marshall', () =>
+  jest.fn(() => ({
+    process: jest.fn().mockResolvedValue({})
+  }))
+)
+jest.mock('../lib/helpers/reportResults', () => ({
+  reportResults: jest.fn().mockReturnValue({ countErrors: 0, countWarnings: 0 })
+}))
+jest.mock('../lib/packageManager', () => ({
+  process: jest.fn()
+}))
+jest.mock('../lib/helpers/cliPrompt.js', () => ({
+  prompt: jest.fn().mockResolvedValue({ install: true }),
+  autoContinue: jest.fn().mockResolvedValue({ install: true })
+}))
+
+describe('npq CLI script', () => {
+  beforeEach(() => {
+    // Reset modules to ensure mocks are fresh for each test.
+    jest.resetModules()
+    // Clear mock history on the shared instance and the constructor.
+    const { Spinner } = require('../lib/helpers/cliSpinner')
+    mockSpinnerInstance.start.mockClear()
+    mockSpinnerInstance.stop.mockClear()
+    Spinner.mockClear()
+  })
+
+  test('should initialize and start spinner in interactive mode without --plain flag', async () => {
+    // Arrange
+    const { CliParser } = require('../lib/cli')
+    const { isInteractiveTerminal } = require('../lib/helpers/cliSupportHandler')
+    const { Spinner } = require('../lib/helpers/cliSpinner')
+
+    CliParser.parseArgsFull.mockReturnValue({ packages: ['express'], plain: false, dryRun: true })
+    isInteractiveTerminal.mockReturnValue(true)
+
+    // Act: Dynamically require the script to run it.
+    require('../bin/npq.js')
+    // Wait for async operations in the script to settle.
+    await new Promise(process.nextTick)
+
+    // Assert
+    expect(Spinner).toHaveBeenCalledTimes(1)
+    expect(mockSpinnerInstance.start).toHaveBeenCalledTimes(1)
+  })
+
+  test('should not initialize spinner when --plain flag is used', async () => {
+    // Arrange
+    const { CliParser } = require('../lib/cli')
+    const { isInteractiveTerminal } = require('../lib/helpers/cliSupportHandler')
+    const { Spinner } = require('../lib/helpers/cliSpinner')
+
+    CliParser.parseArgsFull.mockReturnValue({ packages: ['express'], plain: true, dryRun: true })
+    isInteractiveTerminal.mockReturnValue(true)
+
+    // Act
+    require('../bin/npq.js')
+    await new Promise(process.nextTick)
+
+    // Assert
+    expect(Spinner).not.toHaveBeenCalled()
+    expect(mockSpinnerInstance.start).not.toHaveBeenCalled()
+  })
+
+  test('should not initialize spinner in non-interactive mode', async () => {
+    // Arrange
+    const { CliParser } = require('../lib/cli')
+    const { isInteractiveTerminal } = require('../lib/helpers/cliSupportHandler')
+    const { Spinner } = require('../lib/helpers/cliSpinner')
+
+    CliParser.parseArgsFull.mockReturnValue({ packages: ['express'], plain: false, dryRun: true })
+    isInteractiveTerminal.mockReturnValue(false)
+
+    // Act
+    require('../bin/npq.js')
+    await new Promise(process.nextTick)
+
+    // Assert
+    expect(Spinner).not.toHaveBeenCalled()
+    expect(mockSpinnerInstance.start).not.toHaveBeenCalled()
+  })
+})

package/__tests__/cliPrompt.test.js

@@ -0,0 +1,409 @@
+const { prompt } = require('../lib/helpers/cliPrompt')
+const readline = require('node:readline/promises')
+
+// Mock readline module
+jest.mock('node:readline/promises', () => ({
+  createInterface: jest.fn()
+}))
+
+describe('cliPrompt', () => {
+  let mockRl
+
+  beforeEach(() => {
+    mockRl = {
+      question: jest.fn(),
+      close: jest.fn()
+    }
+    readline.createInterface.mockReturnValue(mockRl)
+
+    // Mock console.log to avoid output during tests
+    jest.spyOn(console, 'log').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+    if (console.log.mockRestore) {
+      console.log.mockRestore()
+    }
+  })
+
+  describe('parameter validation', () => {
+    test('should throw error when message is missing', async () => {
+      await expect(prompt({ name: 'test' })).rejects.toThrow('Message is required for prompt')
+    })
+
+    test('should throw error when name is missing', async () => {
+      await expect(prompt({ message: 'Test message?' })).rejects.toThrow(
+        'Name is required for prompt'
+      )
+    })
+
+    test('should throw error when both name and message are missing', async () => {
+      await expect(prompt({})).rejects.toThrow('Message is required for prompt')
+    })
+  })
+
+  describe('successful prompts', () => {
+    test('should return true for "y" input', async () => {
+      mockRl.question.mockResolvedValue('y')
+
+      const result = await prompt({
+        name: 'install',
+        message: 'Do you want to install?'
+      })
+
+      expect(result).toEqual({ install: true })
+      expect(mockRl.question).toHaveBeenCalledWith('Do you want to install? (y/N) ')
+      expect(mockRl.close).toHaveBeenCalled()
+    })
+
+    test('should return true for "yes" input', async () => {
+      mockRl.question.mockResolvedValue('yes')
+
+      const result = await prompt({
+        name: 'confirm',
+        message: 'Are you sure?'
+      })
+
+      expect(result).toEqual({ confirm: true })
+    })
+
+    test('should return false for "n" input', async () => {
+      mockRl.question.mockResolvedValue('n')
+
+      const result = await prompt({
+        name: 'proceed',
+        message: 'Continue?'
+      })
+
+      expect(result).toEqual({ proceed: false })
+    })
+
+    test('should return false for "no" input', async () => {
+      mockRl.question.mockResolvedValue('no')
+
+      const result = await prompt({
+        name: 'delete',
+        message: 'Delete files?'
+      })
+
+      expect(result).toEqual({ delete: false })
+    })
+
+    test('should handle case-insensitive input', async () => {
+      mockRl.question.mockResolvedValue('YES')
+
+      const result = await prompt({
+        name: 'test',
+        message: 'Test?'
+      })
+
+      expect(result).toEqual({ test: true })
+    })
+
+    test('should trim whitespace from input', async () => {
+      mockRl.question.mockResolvedValue('  y  ')
+
+      const result = await prompt({
+        name: 'test',
+        message: 'Test?'
+      })
+
+      expect(result).toEqual({ test: true })
+    })
+  })
+
+  describe('default value handling', () => {
+    test('should use default false when user presses Enter', async () => {
+      mockRl.question.mockResolvedValue('')
+
+      const result = await prompt({
+        name: 'install',
+        message: 'Install package?'
+      })
+
+      expect(result).toEqual({ install: false })
+      expect(mockRl.question).toHaveBeenCalledWith('Install package? (y/N) ')
+    })
+
+    test('should use default true when specified and user presses Enter', async () => {
+      mockRl.question.mockResolvedValue('')
+
+      const result = await prompt({
+        name: 'continue',
+        message: 'Continue process?',
+        default: true
+      })
+
+      expect(result).toEqual({ continue: true })
+      expect(mockRl.question).toHaveBeenCalledWith('Continue process? (Y/n) ')
+    })
+
+    test('should show correct prompt indicators for default values', async () => {
+      mockRl.question.mockResolvedValue('y')
+
+      await prompt({
+        name: 'test',
+        message: 'Test with default false?',
+        default: false
+      })
+
+      expect(mockRl.question).toHaveBeenCalledWith('Test with default false? (y/N) ')
+    })
+  })
+
+  describe('invalid input handling', () => {
+    test('should log error message when invalid input is provided', () => {
+      // Test the logic path for invalid input without actual recursion
+      const invalidInputs = ['maybe', '1', 'true', 'false', 'ok', 'sure', 'xyz']
+
+      invalidInputs.forEach((input) => {
+        const normalized = input.trim().toLowerCase()
+        const isValidInput = ['y', 'yes', 'n', 'no'].includes(normalized)
+        expect(isValidInput).toBe(false)
+      })
+    })
+
+    test('should recognize valid inputs correctly', () => {
+      const validInputs = ['y', 'yes', 'n', 'no', 'Y', 'YES', 'N', 'NO', '  y  ', '  no  ']
+
+      validInputs.forEach((input) => {
+        const normalized = input.trim().toLowerCase()
+        const isValidInput = ['y', 'yes', 'n', 'no'].includes(normalized)
+        expect(isValidInput).toBe(true)
+      })
+    })
+
+    test('should handle invalid input and retry successfully', async () => {
+      // Create a mock that returns invalid input first, then valid input
+      let callCount = 0
+      mockRl.question.mockImplementation(() => {
+        callCount++
+        if (callCount === 1) {
+          return Promise.resolve('invalid')
+        }
+        return Promise.resolve('y')
+      })
+
+      // Mock the second readline interface creation for the retry
+      let interfaceCallCount = 0
+      const mockRl2 = {
+        question: jest.fn().mockResolvedValue('y'),
+        close: jest.fn()
+      }
+
+      readline.createInterface.mockImplementation(() => {
+        interfaceCallCount++
+        if (interfaceCallCount === 1) {
+          return mockRl
+        }
+        return mockRl2
+      })
+
+      const result = await prompt({
+        name: 'test',
+        message: 'Test?'
+      })
+
+      expect(console.log).toHaveBeenCalledWith('Please answer with y/yes or n/no.')
+      expect(result).toEqual({ test: true })
+      expect(mockRl.close).toHaveBeenCalled()
+      expect(mockRl2.close).toHaveBeenCalled()
+    })
+  })
+
+  describe('readline interface management', () => {
+    test('should create readline interface with correct options', async () => {
+      mockRl.question.mockResolvedValue('y')
+
+      await prompt({
+        name: 'test',
+        message: 'Test?'
+      })
+
+      expect(readline.createInterface).toHaveBeenCalledWith({
+        input: process.stdin,
+        output: process.stdout
+      })
+    })
+
+    test('should close readline interface even if error occurs', async () => {
+      mockRl.question.mockRejectedValue(new Error('Test error'))
+
+      await expect(
+        prompt({
+          name: 'test',
+          message: 'Test?'
+        })
+      ).rejects.toThrow('Test error')
+
+      expect(mockRl.close).toHaveBeenCalled()
+    })
+  })
+
+  describe('return value format', () => {
+    test('should return object with specified property name', async () => {
+      mockRl.question.mockResolvedValue('y')
+
+      const result = await prompt({
+        name: 'customProperty',
+        message: 'Test?'
+      })
+
+      expect(result).toHaveProperty('customProperty')
+      expect(result.customProperty).toBe(true)
+      expect(Object.keys(result)).toHaveLength(1)
+    })
+
+    test('should handle different property names correctly', async () => {
+      mockRl.question.mockResolvedValue('n')
+
+      const result = await prompt({
+        name: 'shouldProceed',
+        message: 'Proceed?'
+      })
+
+      expect(result).toEqual({ shouldProceed: false })
+    })
+  })
+
+  describe('autoContinue', () => {
+    const { autoContinue } = require('../lib/helpers/cliPrompt')
+    let mockWrite, originalWrite
+
+    beforeEach(() => {
+      // Mock process.stdout.write to capture output
+      originalWrite = process.stdout.write
+      mockWrite = jest.fn()
+      process.stdout.write = mockWrite
+
+      // Mock setTimeout to speed up tests
+      jest.useFakeTimers()
+    })
+
+    afterEach(() => {
+      // Restore original stdout.write
+      process.stdout.write = originalWrite
+      jest.useRealTimers()
+    })
+
+    test('should return object with specified property name', async () => {
+      const promise = autoContinue({
+        name: 'install',
+        message: 'Auto-installing in ',
+        timeInSeconds: 2
+      })
+
+      // Fast-forward all timers
+      jest.runAllTimers()
+
+      const result = await promise
+      expect(result).toEqual({ install: true })
+    })
+
+    test('should handle custom timeInSeconds', async () => {
+      const promise = autoContinue({
+        name: 'proceed',
+        message: 'Proceeding in ',
+        timeInSeconds: 3
+      })
+
+      // Fast-forward all timers
+      jest.runAllTimers()
+
+      const result = await promise
+      expect(result).toEqual({ proceed: true })
+    })
+
+    test('should use default timeInSeconds of 5 when not specified', async () => {
+      const promise = autoContinue({
+        name: 'default',
+        message: 'Starting in '
+      })
+
+      // Fast-forward all timers
+      jest.runAllTimers()
+
+      const result = await promise
+      expect(result).toEqual({ default: true })
+    }, 10000) // 10 second timeout
+
+    test('should write countdown to stdout', async () => {
+      const promise = autoContinue({
+        name: 'test',
+        message: 'Testing in ',
+        timeInSeconds: 3
+      })
+
+      // Fast-forward all timers
+      jest.runAllTimers()
+
+      await promise
+
+      // Should write initial message with starting number
+      expect(mockWrite).toHaveBeenCalledWith('Testing in 3')
+    })
+
+    test('should handle single digit countdown correctly', async () => {
+      const promise = autoContinue({
+        name: 'test',
+        message: 'Starting in ',
+        timeInSeconds: 2
+      })
+
+      // Fast-forward all timers
+      jest.runAllTimers()
+
+      await promise
+
+      // Should write initial message
+      expect(mockWrite).toHaveBeenCalledWith('Starting in 2')
+    })
+
+    test('should handle double digit to single digit countdown with padding', async () => {
+      const promise = autoContinue({
+        name: 'test',
+        message: 'Waiting ',
+        timeInSeconds: 10
+      })
+
+      // Fast-forward all timers
+      jest.runAllTimers()
+
+      await promise
+
+      // Should write initial message with double digit
+      expect(mockWrite).toHaveBeenCalledWith('Waiting 10')
+    }, 15000) // 15 second timeout
+
+    test('should call console.log at the end', async () => {
+      const mockConsoleLog = jest.spyOn(console, 'log').mockImplementation(() => {})
+
+      const promise = autoContinue({
+        name: 'test',
+        message: 'Done in ',
+        timeInSeconds: 1
+      })
+
+      // Fast-forward all timers
+      jest.runAllTimers()
+
+      await promise
+
+      expect(mockConsoleLog).toHaveBeenCalledWith()
+      mockConsoleLog.mockRestore()
+    })
+
+    test('should handle default parameters', async () => {
+      const promise = autoContinue()
+
+      // Fast-forward all timers
+      jest.runAllTimers()
+
+      const result = await promise
+
+      // Should handle undefined name gracefully
+      expect(result).toEqual({ undefined: true })
+    }, 10000) // 10 second timeout
+  })
+})

package/__tests__/marshalls.base.test.js

@@ -23,7 +23,7 @@ test('checkPackage returns validation data if it was a success', async () => {
     }
   }
 
-  const result = await testMarshall.checkPackage('express', ctx, {})
+  const result = await testMarshall.checkPackage({ packageName: 'express' }, ctx, {})
   expect(result).toEqual('validation-result')
 })