npq 3.22.0 → 3.23.0

package/README.md

@@ -130,6 +130,7 @@ NPQ_PKG_MGR=pnpm npx npq install fastify
 
 ```bash
 alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"
+pnpm --filter workspace... add express
 ```
 
 Note: `npq` by default will offload all commands and their arguments to the `npm` (or other package manager as specified) after it finished its due-diligence checks for the respective packages.
@@ -149,11 +150,32 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | expired domains | Normalizes and checks complete maintainer email hosts, then corroborates a simple two-label DNS failure through authoritative RDAP before warning | Multipart and otherwise inconclusive results are reported as not evaluated; see [expired-domain marshall documentation](docs/feature/expired-domains.md)
 | signatures | Will compare the package's signature as it shows on the registry's packument with signing keys published by the selected registry | Reports `not evaluated` if the selected registry does not expose signing keys
 | provenance | Will verify the package's attestations of provenance metadata for the published package, and **error** on [provenance regression](docs/feature/provenance.md) (an older semver had registry provenance metadata but the version you install does not) | Reports `not evaluated` if the selected registry does not expose signing keys or attestations
-| 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
+| version-maturity | Will show an error if the specific version being installed was published less than 7 days ago | Suggests the highest older semver outside npq's 30-day version-recency window when one is available
 | 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 is deprecated on npm or if its GitHub repository has been archived. | Helps identify packages that are no longer maintained or recommended for use. Set `GITHUB_TOKEN` environment variable for higher GitHub API rate limits.
 
+### Older release suggestions
+
+When a requested version fails the version-maturity check, npq may show the highest older
+semver published outside its 30-day package-version recency window:
+
+```text
+ │
+ │ ℹ Suggested older release · @openai/codex@0.121.0 — published 33 days ago
+ │   Clears npq's package-version recency windows. Re-run npq to audit this
+ │   version; compatibility is not evaluated.
+```
+
+The suggestion:
+
+- can cross a major-version boundary for tags such as `latest`;
+- is based on cached package publication metadata and is not automatically installed;
+- is not a statement that the older release is safe or that it passes every npq check;
+- does not evaluate API or runtime compatibility.
+
+Run npq again with the suggested version and review its compatibility before installing it.
+
 ### Disabling Marshalls
 
 To disable a marshall altogether, set an environment variable using with the marshall's shortname.

package/lib/cli.js

@@ -3,6 +3,7 @@
 const { parseArgs } = require('node:util')
 const npa = require('npm-package-arg')
 const pkg = require('../package.json')
+const { parsePackageManagerArguments } = require('./helpers/packageManagerArgumentParser')
 
 const INSTALL_SUBCOMMANDS = new Set([
   'install',
@@ -145,22 +146,11 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
   }
 
   static parseArgsMinimal() {
-    const config = {
-      allowPositionals: true,
-      strict: false,
-      options: {
-        install: {
-          type: 'string',
-          short: 'i',
-          default: 'install'
-        },
-        registry: { type: 'string' },
-        userconfig: { type: 'string' },
-        globalconfig: { type: 'string' }
-      }
-    }
-
-    const { values, positionals } = parseArgs(config)
+    const packageManager = process.env.NPQ_PKG_MGR || 'npm'
+    const { values, positionals } = parsePackageManagerArguments({
+      packageManager,
+      args: process.argv.slice(2)
+    })
 
     const earlyExitNoInstall = true
     const normalizedPackages = this._extractPackagesFromPositionals(positionals, earlyExitNoInstall)

package/lib/helpers/packageManagerArgumentParser.js

@@ -0,0 +1,39 @@
+'use strict'
+
+const { parseArgs } = require('node:util')
+
+const BASE_OPTIONS = {
+  install: {
+    type: 'string',
+    short: 'i',
+    default: 'install'
+  },
+  registry: { type: 'string' },
+  userconfig: { type: 'string' },
+  globalconfig: { type: 'string' }
+}
+
+function parsePackageManagerArguments({ packageManager, args }) {
+  const options =
+    packageManager === 'pnpm'
+      ? {
+          ...BASE_OPTIONS,
+          filter: { type: 'string', short: 'F', multiple: true },
+          'filter-prod': { type: 'string', multiple: true }
+        }
+      : BASE_OPTIONS
+
+  const config = {
+    allowPositionals: true,
+    strict: false,
+    options
+  }
+
+  if (args !== undefined) {
+    config.args = args
+  }
+
+  return parseArgs(config)
+}
+
+module.exports.parsePackageManagerArguments = parsePackageManagerArguments

package/lib/helpers/reportResults.js

@@ -160,6 +160,7 @@ function reportResults(marshallResults, { plain = false } = {}) {
 
       if (isPackageMalicious) {
         countErrors = 1
+        result.suggestions = []
 
         // Rich formatting version
         const topicRich = styleText(
@@ -242,6 +243,38 @@ function reportResults(marshallResults, { plain = false } = {}) {
       })
     }
 
+    if (!isPackageMalicious && result.suggestions && result.suggestions.length > 0) {
+      result.suggestions.forEach((suggestion) => {
+        const iconRich = styleText(['cyan'], 'ℹ')
+        const labelRich = styleText(['cyan', 'bold'], 'Suggested older release')
+        const headline = `${suggestion.packageSpec} — published ${suggestion.ageDays} days ago`
+        const detail =
+          "Clears npq's package-version recency windows. Re-run npq to audit this version; compatibility is not evaluated."
+        const suggestionIndent = ` ${styleText(['gray'], '│')}   `
+        const headlineWidth = Math.max(
+          20,
+          terminalWidth - getDisplayLength(' │ ℹ Suggested older release · ') - 2
+        )
+        const detailWidth = Math.max(20, terminalWidth - getDisplayLength(' │   ') - 2)
+        const wrappedHeadline = wrapTextWithIndent(
+          headline,
+          headlineWidth,
+          suggestionIndent
+        )
+        const wrappedDetail = wrapTextWithIndent(detail, detailWidth, suggestionIndent)
+
+        resultsForPrettyPrint += `\n ${prefixRich}`
+        resultsForPrettyPrint +=
+          `\n ${prefixRich} ${iconRich} ${labelRich} ${separatorRich} ${wrappedHeadline}`
+        resultsForPrettyPrint += `\n${suggestionIndent}${wrappedDetail}`
+
+        resultsForPlainTextPrint +=
+          `\n  SUGGESTION: ${suggestion.packageSpec} was published ${suggestion.ageDays} days ago ` +
+          'and clears the package-version recency windows. Re-run npq to audit it; ' +
+          'compatibility is not evaluated.'
+      })
+    }
+
     // Close rich formatting box
     resultsForPrettyPrint += `\n ${styleText(['dim'], '└─')}`
   })
@@ -297,8 +330,10 @@ function marshallResultsToIssuesPerPackage(results) {
       pkg,
       errors: [],
       warnings: [],
-      notEvaluated: []
+      notEvaluated: [],
+      suggestions: []
     }
+    const suggestionKeys = new Set()
     for (const marshall of allMarshallResultsList) {
       for (const value of Object.values(marshall)) {
         if (value.errors && value.errors.length > 0) {
@@ -333,12 +368,24 @@ function marshallResultsToIssuesPerPackage(results) {
           }))
           issues.notEvaluated.push(skippedChecks)
         }
+        if (value.suggestions && value.suggestions.length > 0) {
+          value.suggestions.forEach((entry) => {
+            const suggestion = { ...entry }
+            delete suggestion.pkg
+            const key = `${suggestion.type}:${suggestion.packageSpec}`
+            if (!suggestionKeys.has(key)) {
+              suggestionKeys.add(key)
+              issues.suggestions.push(suggestion)
+            }
+          })
+        }
       }
     }
     if (
       issues.errors.length > 0 ||
       issues.warnings.length > 0 ||
-      issues.notEvaluated.length > 0
+      issues.notEvaluated.length > 0 ||
+      issues.suggestions.length > 0
     ) {
       issuesPerPackage.push(issues)
     }

package/lib/helpers/versionAge.js

@@ -0,0 +1,65 @@
+'use strict'
+
+const semver = require('semver')
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const MAX_VERSION_RECENCY_DAYS = 30
+
+function getRoundedVersionAgeDays(publishedAt, now = Date.now()) {
+  const publishedAtMs = Date.parse(publishedAt)
+  const nowMs = now instanceof Date ? now.getTime() : Number(now)
+
+  if (Number.isNaN(publishedAtMs) || Number.isNaN(nowMs)) {
+    return null
+  }
+
+  const ageMs = nowMs - publishedAtMs
+  return ageMs > 0 ? Math.round(ageMs / DAY_MS) : 0
+}
+
+function findAlternativeVersion({
+  packageInfo,
+  targetVersion,
+  requestedVersion,
+  now = Date.now()
+}) {
+  if (
+    !packageInfo ||
+    !packageInfo.versions ||
+    !packageInfo.time ||
+    !semver.valid(targetVersion)
+  ) {
+    return null
+  }
+
+  const targetIsStable = semver.prerelease(targetVersion) === null
+  const requestedRange =
+    typeof requestedVersion === 'string' && !semver.valid(requestedVersion)
+      ? semver.validRange(requestedVersion)
+      : null
+
+  const candidates = Object.keys(packageInfo.versions)
+    .filter((version) => semver.valid(version) && semver.lt(version, targetVersion))
+    .filter((version) => !targetIsStable || semver.prerelease(version) === null)
+    .filter((version) => !requestedRange || semver.satisfies(version, requestedRange))
+    .map((version) => {
+      const publishedAt = packageInfo.time[version]
+      const ageDays = getRoundedVersionAgeDays(publishedAt, now)
+      return { version, publishedAt, ageDays }
+    })
+    .filter(
+      ({ publishedAt, ageDays }) =>
+        typeof publishedAt === 'string' &&
+        ageDays !== null &&
+        ageDays > MAX_VERSION_RECENCY_DAYS
+    )
+    .sort((left, right) => semver.rcompare(left.version, right.version))
+
+  return candidates[0] || null
+}
+
+module.exports = {
+  MAX_VERSION_RECENCY_DAYS,
+  findAlternativeVersion,
+  getRoundedVersionAgeDays
+}

package/lib/marshalls/author.marshall.js

@@ -34,6 +34,7 @@
 
 const BaseMarshall = require('./baseMarshall')
 const Warning = require('../helpers/warning')
+const { MAX_VERSION_RECENCY_DAYS } = require('../helpers/versionAge')
 const { marshallCategories } = require('./constants')
 
 const MARSHALL_NAME = 'author'
@@ -202,7 +203,7 @@ class Marshall extends BaseMarshall {
         )
       }
 
-      if (dateDiffVersionPublished <= 30) {
+      if (dateDiffVersionPublished <= MAX_VERSION_RECENCY_DAYS) {
         throw new Warning(
           `This version was published only ${dateDiffVersionPublished} days ago by ${npmUser.name} <${npmUser.email}>`
         )

package/lib/marshalls/baseMarshall.js

@@ -22,6 +22,7 @@ class BaseMarshall {
       status: null,
       errors: [],
       warnings: [],
+      suggestions: [],
       notEvaluated: [],
       data: {},
       marshall: this.name,
@@ -60,6 +61,13 @@ class BaseMarshall {
           return undefined
         }
 
+        if (err.suggestion && typeof err.suggestion === 'object') {
+          this.setSuggestion({
+            pkg: pkg.packageString,
+            ...err.suggestion
+          })
+        }
+
         this.setMessage(message, Boolean(err instanceof Warning))
         return undefined
       })
@@ -89,6 +97,10 @@ class BaseMarshall {
     })
   }
 
+  setSuggestion(suggestion) {
+    this.ctx.marshalls[this.name].suggestions.push(suggestion)
+  }
+
   /**
    * Resolves a package version string to an actual semver version
    * Handles dist-tags (latest, beta, etc.) and direct semver versions

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

@@ -1,6 +1,7 @@
 'use strict'
 
 const BaseMarshall = require('./baseMarshall')
+const { findAlternativeVersion } = require('../helpers/versionAge')
 const { marshallCategories } = require('./constants')
 
 const MARSHALL_NAME = 'version_maturity'
@@ -35,7 +36,8 @@ class Marshall extends BaseMarshall {
     }
 
     const versionReleaseDate = data.time[packageVersion]
-    const versionDateDiff = new Date() - new Date(versionReleaseDate)
+    const now = Date.now()
+    const versionDateDiff = now - new Date(versionReleaseDate)
     const versionDateDiffInDays = Math.round(versionDateDiff / (1000 * 60 * 60 * 24))
 
     if (versionDateDiffInDays < VERSION_AGE_THRESHOLD) {
@@ -50,9 +52,29 @@ class Marshall extends BaseMarshall {
         timeAgoText = 'day'
       }
 
-      throw new Error(
+      const error = new Error(
         `Detected a recently published version: published ${timeAgoNumber} ${timeAgoText} ago. Consider waiting for community review.`
       )
+      const alternative = findAlternativeVersion({
+        packageInfo: data,
+        targetVersion: packageVersion,
+        requestedVersion: pkg.packageVersion,
+        now
+      })
+
+      if (alternative) {
+        error.suggestion = {
+          type: 'alternative-version',
+          packageName: pkg.packageName,
+          version: alternative.version,
+          packageSpec: `${pkg.packageName}@${alternative.version}`,
+          publishedAt: alternative.publishedAt,
+          ageDays: alternative.ageDays,
+          reason: 'version-recency'
+        }
+      }
+
+      throw error
     }
 
     return pkg

package/package.json

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