npq 3.6.0 → 3.7.0

package/README.md

@@ -98,6 +98,7 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | signatures | Will compare the package's signature as it shows on the registry's pakument with the keys published on the npmjs.com registry 
 | 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.
 
 ### Disabling Marshalls
 
@@ -127,6 +128,7 @@ Here are all the available environment variable names for disabling specific mar
 | snyk | `MARSHALL_DISABLE_SNYK` | Disable Snyk vulnerability checks |
 | 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 |
 
 ### Run checks on package without installing it:
 

package/__tests__/marshalls.newBin.test.js

@@ -0,0 +1,441 @@
+'use strict'
+
+const NewBinMarshall = require('../lib/marshalls/newbin.marshall')
+const PackageRepoUtils = require('../lib/helpers/packageRepoUtils')
+
+jest.mock('../lib/helpers/packageRepoUtils')
+
+describe('NewBinMarshall', () => {
+  let packageRepoUtilsMock
+  let newBinMarshall
+
+  beforeEach(() => {
+    packageRepoUtilsMock = new PackageRepoUtils()
+    newBinMarshall = new NewBinMarshall({ packageRepoUtils: packageRepoUtilsMock })
+
+    // Mock context and task for the marshall
+    newBinMarshall.init(
+      {
+        marshalls: {
+          newBin: {
+            status: null,
+            errors: [],
+            warnings: [],
+            data: {}
+          }
+        },
+        pkgs: [] // Not directly used by validate but part of ctx
+      },
+      { output: '' } // Mock task object
+    )
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+  })
+
+  const mockPackageInfo = (packageName, versions) => {
+    const fullPackageData = {
+      name: packageName,
+      versions: {},
+      'dist-tags': {}
+    }
+    let latestTag = null
+    Object.keys(versions).forEach((vStr) => {
+      fullPackageData.versions[vStr] = {
+        name: packageName,
+        version: vStr,
+        bin: versions[vStr].bin
+        // other fields like scripts, dependencies might be needed if other marshalls run
+      }
+      if (!latestTag || require('semver').gt(vStr, latestTag)) {
+        latestTag = vStr
+      }
+    })
+    if (latestTag) {
+      fullPackageData['dist-tags'].latest = latestTag
+    }
+    return fullPackageData
+  }
+
+  test('should return correct title', () => {
+    const newBinMarshall = new NewBinMarshall({
+      packageRepoUtils: null
+    })
+
+    const title = newBinMarshall.title()
+    expect(title).toBe('Checking for new binaries introduced in package.json')
+  })
+
+  it('should pass if no previous version exists', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.0',
+      packageString: 'test-pkg@1.0.0'
+    }
+    const versions = {
+      '1.0.0': { bin: { 'my-cli': 'cli.js' } }
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).resolves.toBeUndefined()
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(0)
+  })
+
+  it('should pass if bin field is the same', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: { 'my-cli': 'cli.js' } },
+      '1.0.1': { bin: { 'my-cli': 'cli.js' } }
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).resolves.toBeUndefined()
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(0)
+  })
+
+  it('should warn if a new binary is introduced (object format)', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: { 'old-cli': 'old.js' } },
+      '1.0.1': { bin: { 'old-cli': 'old.js', 'new-cli': 'new.js' } }
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      'New binaries detected for test-pkg@1.0.1'
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(1)
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "introduces a new binary 'new-cli'"
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "compared to version '1.0.0'"
+    )
+  })
+
+  it('should warn if a new binary is introduced (string format to object)', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    // Previous version has string bin, new one has object bin
+    const versions = {
+      '1.0.0': { bin: 'old.js' }, // This will be normalized to { 'test-pkg': 'old.js' }
+      '1.0.1': { bin: { 'test-pkg': 'old.js', 'new-cli': 'new.js' } }
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      'New binaries detected for test-pkg@1.0.1'
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(1)
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "introduces a new binary 'new-cli'"
+    )
+  })
+
+  it('should warn if a new binary is introduced (string format for both, new name)', async () => {
+    // This case implies the package name itself changed or the bin refers to a different command name
+    // For this marshall, we primarily care about new keys in the (normalized) bin object.
+    // If package name changes, it's a different package, not really a "new bin" for the *same* package.
+    // However, if `bin` was a string `old-bin-name.js` and becomes `new-bin-name.js`,
+    // and assuming the package name (key) remains the same, this is not a *new* binary key.
+    // This test will check introduction of a string bin when there was none.
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: null }, // No bin before
+      '1.0.1': { bin: 'new.js' } // New bin (string)
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      'New binaries detected for test-pkg@1.0.1'
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(1)
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "introduces a new binary 'test-pkg'"
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain("command: 'new.js'")
+  })
+
+  it('should pass if a binary is removed', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: { 'old-cli': 'old.js', 'to-remove': 'remove.js' } },
+      '1.0.1': { bin: { 'old-cli': 'old.js' } }
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).resolves.toBeUndefined()
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(0)
+  })
+
+  it('should pass if bin changes from string to object but represents the same binary', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: 'cli.js' }, // Normalized: { 'test-pkg': 'cli.js' }
+      '1.0.1': { bin: { 'test-pkg': 'cli.js' } }
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).resolves.toBeUndefined()
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(0)
+  })
+
+  it('should pass if bin changes from object to string but represents the same binary', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: { 'test-pkg': 'cli.js' } },
+      '1.0.1': { bin: 'cli.js' } // Normalized: { 'test-pkg': 'cli.js' }
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).resolves.toBeUndefined()
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(0)
+  })
+
+  it('should handle package version being a dist-tag like "latest"', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: 'latest',
+      packageString: 'test-pkg@latest'
+    }
+    const versions = {
+      '1.0.0': { bin: { 'my-cli': 'cli.js' } },
+      '1.0.1': { bin: { 'my-cli': 'cli.js', 'new-cli': 'new.js' } } // latest points to 1.0.1
+    }
+    const mockPkgInfo = mockPackageInfo('test-pkg', versions)
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPkgInfo)
+    // Mock getSemVer to resolve 'latest' to '1.0.1'
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => {
+      if (version === 'latest') return '1.0.1'
+      return version
+    })
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      'New binaries detected for test-pkg@latest'
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(1)
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "introduces a new binary 'new-cli'"
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "compared to version '1.0.0'"
+    )
+  })
+
+  it('should pass if package info cannot be fetched', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.0',
+      packageString: 'test-pkg@1.0.0'
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(null) // Simulate failed fetch
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).resolves.toBeUndefined()
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(0)
+  })
+
+  it('should pass if target version string cannot be resolved', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: 'nonexistent-tag',
+      packageString: 'test-pkg@nonexistent-tag'
+    }
+    const versions = { '1.0.0': { bin: 'cli.js' } }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockResolvedValue(null) // Simulate tag not resolving
+
+    await expect(newBinMarshall.validate(pkg)).resolves.toBeUndefined()
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(0)
+  })
+
+  it('should handle multiple new binaries being introduced', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: { 'old-cli': 'old.js' } },
+      '1.0.1': { bin: { 'old-cli': 'old.js', 'new-cli-1': 'new1.js', 'new-cli-2': 'new2.js' } }
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      'New binaries detected for test-pkg@1.0.1'
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(2)
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "introduces a new binary 'new-cli-1'"
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[1].message).toContain(
+      "introduces a new binary 'new-cli-2'"
+    )
+  })
+
+  it('should pass if the new version has no bin field but old one did', async () => {
+    const pkg = {
+      packageName: 'test-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'test-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: { 'old-cli': 'old.js' } },
+      '1.0.1': { bin: null } // No bin in new version
+    }
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPackageInfo('test-pkg', versions))
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).resolves.toBeUndefined()
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(0)
+  })
+
+  it('should correctly use package name from version data for string bin normalization', async () => {
+    // Scenario: pkg.packageName might be different from the actual name in package.json (e.g. alias)
+    // The marshall should use the name from the fetched package.json for normalization.
+    const pkg = {
+      packageName: 'alias-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'alias-pkg@1.0.1'
+    }
+    const actualPackageName = 'actual-pkg-name'
+
+    // Mock getPackageInfo to return versions with the actual package name
+    const versions = {
+      '1.0.0': { bin: null }, // No bin in old version
+      '1.0.1': { bin: 'cli.js' } // Bin is a string, should be keyed by actualPackageName
+    }
+    const mockPkgData = mockPackageInfo(actualPackageName, versions) // mockPackageInfo uses the name for versions too
+
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPkgData)
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      `New binaries detected for ${pkg.packageString}`
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(1)
+    // Check that the binary name used in the warning is the actualPackageName
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      `introduces a new binary '${actualPackageName}'`
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(`command: 'cli.js'`)
+  })
+
+  it('should use pkg.packageName when newVersionData.name is falsy (line 40 coverage)', async () => {
+    const pkg = {
+      packageName: 'fallback-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'fallback-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: null },
+      '1.0.1': { bin: 'cli.js' } // This version will have name: falsy
+    }
+    const mockPkgData = mockPackageInfo('fallback-pkg', versions)
+    // Set name to falsy to test the fallback in line 40: newVersionData.name || pkg.packageName
+    mockPkgData.versions['1.0.1'].name = ''
+
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPkgData)
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      'New binaries detected for fallback-pkg@1.0.1'
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(1)
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "introduces a new binary 'fallback-pkg'"
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain("command: 'cli.js'")
+  })
+
+  it('should use pkg.packageName when previousVersionData.name is falsy (line 56 coverage)', async () => {
+    const pkg = {
+      packageName: 'fallback-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'fallback-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: 'old.js' }, // This version will have name: falsy
+      '1.0.1': { bin: { 'fallback-pkg': 'old.js', 'new-cli': 'new.js' } }
+    }
+    const mockPkgData = mockPackageInfo('fallback-pkg', versions)
+    // Set name to falsy to test the fallback in line 56: previousVersionData.name || pkg.packageName
+    mockPkgData.versions['1.0.0'].name = undefined
+
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPkgData)
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      'New binaries detected for fallback-pkg@1.0.1'
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(1)
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "introduces a new binary 'new-cli'"
+    )
+  })
+
+  it('should use pkg.packageName when both version data names are falsy (covers both lines)', async () => {
+    const pkg = {
+      packageName: 'double-fallback-pkg',
+      packageVersion: '1.0.1',
+      packageString: 'double-fallback-pkg@1.0.1'
+    }
+    const versions = {
+      '1.0.0': { bin: null },
+      '1.0.1': { bin: 'cli.js' }
+    }
+    const mockPkgData = mockPackageInfo('double-fallback-pkg', versions)
+    // Set both names to falsy values to test both fallbacks
+    mockPkgData.versions['1.0.0'].name = null
+    mockPkgData.versions['1.0.1'].name = ''
+
+    packageRepoUtilsMock.getPackageInfo.mockResolvedValue(mockPkgData)
+    packageRepoUtilsMock.getSemVer.mockImplementation(async (name, version) => version)
+
+    await expect(newBinMarshall.validate(pkg)).rejects.toThrow(
+      'New binaries detected for double-fallback-pkg@1.0.1'
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings).toHaveLength(1)
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain(
+      "introduces a new binary 'double-fallback-pkg'"
+    )
+    expect(newBinMarshall.ctx.marshalls.newBin.warnings[0].message).toContain("command: 'cli.js'")
+  })
+})

package/__tests__/marshalls.typosquatting.test.js

@@ -8,7 +8,7 @@ describe('Typosquatting Marshall', () => {
 
     // Mock the top packages data to include duplicates
     const originalTopPackages = require('../data/top-packages.json')
-    
+
     // Create a test package that would match multiple similar packages
     const pkg = {
       packageName: 'ghtml' // This should match 'html' which appears multiple times in the data
@@ -21,18 +21,20 @@ describe('Typosquatting Marshall', () => {
     } catch (error) {
       // Check that the error message doesn't contain duplicate entries
       const errorMessage = error.message
-      expect(errorMessage).toContain('Package name could be a typosquatting attempt for popular package(s):')
-      
+      expect(errorMessage).toContain(
+        'Package name could be a typosquatting attempt for popular package(s):'
+      )
+
       // Extract the package names from the error message
       const packagesList = errorMessage.split('popular package(s): ')[1]
       const packages = packagesList.split(', ')
-      
+
       // Check that there are no duplicates
       const uniquePackages = [...new Set(packages)]
       expect(packages.length).toBe(uniquePackages.length)
-      
+
       // Verify that 'html' appears only once even though it exists multiple times in the data
-      const htmlCount = packages.filter(pkg => pkg === 'html').length
+      const htmlCount = packages.filter((pkg) => pkg === 'html').length
       expect(htmlCount).toBe(1)
     }
   })
@@ -64,4 +66,4 @@ describe('Typosquatting Marshall', () => {
     const result = await typosquattingMarshall.validate(pkg)
     expect(result).toEqual([])
   })
-})
+})

package/lib/marshalls/newbin.marshall.js

@@ -0,0 +1,88 @@
+'use strict'
+
+const semver = require('semver')
+const BaseMarshall = require('./baseMarshall')
+const Warning = require('../helpers/warning')
+const { marshallCategories } = require('./constants')
+
+const MARSHALL_NAME = 'newBin' // Or a more descriptive name like 'newBinary'
+
+class NewBinMarshall extends BaseMarshall {
+  constructor(options) {
+    super(options)
+    this.name = MARSHALL_NAME
+    // Decide on a category, e.g., PackageHealth or a new one if appropriate
+    this.categoryId = marshallCategories.PackageHealth.id
+  }
+
+  title() {
+    return 'Checking for new binaries introduced in package.json'
+  }
+
+  async validate(pkg) {
+    const fullPackageInfo = await this.packageRepoUtils.getPackageInfo(pkg.packageName)
+    if (!fullPackageInfo || !fullPackageInfo.versions) {
+      // If we can't get package info or versions, skip
+      return
+    }
+
+    const targetVersionString = await this.packageRepoUtils.getSemVer(
+      pkg.packageName,
+      pkg.packageVersion
+    )
+
+    if (!targetVersionString || !fullPackageInfo.versions[targetVersionString]) {
+      // If target version string can't be resolved or doesn't exist in versions
+      return
+    }
+
+    const newVersionData = fullPackageInfo.versions[targetVersionString]
+    const newBin = this.normalizeBin(newVersionData.bin, newVersionData.name || pkg.packageName)
+
+    const allVersions = Object.keys(fullPackageInfo.versions)
+    const olderVersions = allVersions
+      .filter((v) => semver.valid(v) && semver.lt(v, targetVersionString))
+      .sort(semver.rcompare) // Sorts descending, so first is latest older
+
+    if (olderVersions.length === 0) {
+      // No previous version to compare against
+      return
+    }
+
+    const previousVersionString = olderVersions[0]
+    const previousVersionData = fullPackageInfo.versions[previousVersionString]
+    const oldBin = this.normalizeBin(
+      previousVersionData.bin,
+      previousVersionData.name || pkg.packageName
+    )
+
+    const newBinaries = Object.keys(newBin).filter((key) => !oldBin.hasOwnProperty(key))
+
+    if (newBinaries.length > 0) {
+      newBinaries.forEach((binaryName) => {
+        const message = `Package '${pkg.packageString}' introduces a new binary '${binaryName}' (command: '${newBin[binaryName]}') compared to version '${previousVersionString}'.`
+        this.setMessage({ pkg: pkg.packageString, message }, true) // true for warning
+      })
+      // Throw a warning to signal that messages have been set.
+      // The base class's checkPackage will catch this and use the messages.
+      // Note: We only need to throw one Warning, even if multiple binaries are new.
+      // The messages have already been added.
+
+      throw new Warning(`New binaries detected for ${pkg.packageString}`)
+    }
+  }
+
+  normalizeBin(binField, packageJSONName) {
+    if (!binField) {
+      return {}
+    }
+    if (typeof binField === 'string') {
+      // If bin is a string, the key is the package name from package.json
+      return { [packageJSONName]: binField }
+    }
+    // If it's already an object, return as is
+    return binField
+  }
+}
+
+module.exports = NewBinMarshall

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npq",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "marshall your npm/npm package installs with high quality and class 🎖",
   "bin": {
     "npq": "./bin/npq.js",