npq 3.5.5 → 3.6.0

package/README.md

@@ -97,6 +97,7 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | expired domains | Will show a warning if a package has been found with one of its maintainers having an email address that includes an expired domain | Checks a dependency version for a maintainer with an expired domain
 | 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
 
 ### Disabling Marshalls
 
@@ -125,6 +126,7 @@ Here are all the available environment variable names for disabling specific mar
 | signatures | `MARSHALL_DISABLE_SIGNATURES` | Disable registry signature verification |
 | 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 |
 
 ### Run checks on package without installing it:
 

package/__tests__/marshalls.version-maturity.test.js

@@ -0,0 +1,194 @@
+'use strict'
+
+const Marshall = require('../lib/marshalls/version-maturity.marshall')
+
+describe('Version Maturity Marshall', () => {
+  test('should have the correct title', () => {
+    const testMarshall = new Marshall({
+      packageRepoUtils: null
+    })
+
+    expect(testMarshall.title()).toEqual('Checking version maturity')
+  })
+
+  test('should throw error for recently published version (same day)', async () => {
+    const now = new Date()
+    const hoursAgo = new Date(now.getTime() - 2 * 60 * 60 * 1000) // 2 hours ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.0.0': hoursAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow(
+      'detected a recently published version (published 2 hours ago) - consider waiting for community review'
+    )
+  })
+
+  test('should throw error for recently published version (within threshold)', async () => {
+    const now = new Date()
+    const daysAgo = new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000) // 3 days ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.0.0': daysAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow(
+      'detected a recently published version (published 3 days ago) - consider waiting for community review'
+    )
+  })
+
+  test('should throw error for version published exactly 1 day ago', async () => {
+    const now = new Date()
+    const oneDayAgo = new Date(now.getTime() - 24 * 60 * 60 * 1000) // 1 day ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.0.0': oneDayAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow(
+      'detected a recently published version (published 1 day ago) - consider waiting for community review'
+    )
+  })
+
+  test('should pass for version published beyond threshold', async () => {
+    const now = new Date()
+    const weekAgo = new Date(now.getTime() - 8 * 24 * 60 * 60 * 1000) // 8 days ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.0.0': weekAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    const result = await testMarshall.validate({
+      packageName: 'test-package',
+      packageVersion: '1.0.0'
+    })
+
+    expect(result).toEqual({
+      packageName: 'test-package',
+      packageVersion: '1.0.0'
+    })
+  })
+
+  test('should throw error when package time information is missing', async () => {
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({})
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow('could not determine package version information')
+  })
+
+  test('should throw error when version release date is missing', async () => {
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '2.0.0': new Date().toISOString()
+            }
+          })
+        },
+        getSemVer: () => Promise.resolve('1.0.0')
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: '1.0.0'
+      })
+    ).rejects.toThrow('could not determine release date for version 1.0.0')
+  })
+
+  test('should handle version aliases correctly', async () => {
+    const now = new Date()
+    const daysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000) // 2 days ago
+
+    const testMarshall = new Marshall({
+      packageRepoUtils: {
+        getPackageInfo: () => {
+          return Promise.resolve({
+            time: {
+              '1.2.3': daysAgo.toISOString()
+            }
+          })
+        },
+        getSemVer: (packageName, packageVersion) => {
+          if (packageVersion === 'latest') {
+            return Promise.resolve('1.2.3')
+          }
+          return Promise.resolve(packageVersion)
+        }
+      }
+    })
+
+    await expect(
+      testMarshall.validate({
+        packageName: 'test-package',
+        packageVersion: 'latest'
+      })
+    ).rejects.toThrow(
+      'detected a recently published version (published 2 days ago) - consider waiting for community review'
+    )
+  })
+})

package/lib/marshalls/version-maturity.marshall.js

@@ -0,0 +1,67 @@
+'use strict'
+
+const BaseMarshall = require('./baseMarshall')
+const { marshallCategories } = require('./constants')
+
+const MARSHALL_NAME = 'version_maturity'
+const VERSION_AGE_THRESHOLD = 7 // specified in days
+
+class Marshall extends BaseMarshall {
+  constructor(options) {
+    super(options)
+    this.name = MARSHALL_NAME
+    this.categoryId = marshallCategories.PackageHealth.id
+  }
+
+  title() {
+    return 'Checking version maturity'
+  }
+
+  validate(pkg) {
+    let packageData = null
+    return this.packageRepoUtils
+      .getPackageInfo(pkg.packageName)
+      .then((data) => {
+        if (data && data.time) {
+          packageData = data
+          return pkg
+        } else {
+          throw new Error('could not determine package version information')
+        }
+      })
+      .then((pkg) => {
+        return this.packageRepoUtils.getSemVer(pkg.packageName, pkg.packageVersion)
+      })
+      .then((versionResolved) => {
+        const versionReleaseDate = packageData.time[versionResolved]
+
+        if (!versionReleaseDate) {
+          throw new Error(`could not determine release date for version ${versionResolved}`)
+        }
+
+        const versionDateDiff = new Date() - new Date(versionReleaseDate)
+        const versionDateDiffInDays = Math.round(versionDateDiff / (1000 * 60 * 60 * 24))
+
+        if (versionDateDiffInDays < VERSION_AGE_THRESHOLD) {
+          let timeAgoText = 'days'
+          let timeAgoNumber = versionDateDiffInDays
+
+          if (versionDateDiffInDays === 0) {
+            timeAgoText = 'hours'
+            const versionDateDiffInHours = Math.round(versionDateDiff / (1000 * 60 * 60))
+            timeAgoNumber = versionDateDiffInHours
+          } else if (versionDateDiffInDays === 1) {
+            timeAgoText = 'day'
+          }
+
+          throw new Error(
+            `detected a recently published version (published ${timeAgoNumber} ${timeAgoText} ago) - consider waiting for community review`
+          )
+        }
+
+        return pkg
+      })
+  }
+}
+
+module.exports = Marshall

package/package.json

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