npq 3.23.2 → 3.24.0

package/README.md

@@ -222,6 +222,18 @@ npq install express --dry-run
 npq install express --plain
 ```
 
+### Machine-readable audits
+
+Use `--json` for a non-interactive, audit-only result suitable for CI:
+
+```sh
+npq install express --json
+```
+
+JSON mode never invokes the package manager. It exits `0` for a clean audit,
+`1` for findings, and `2` when the audit cannot complete. See
+[JSON audit output](docs/feature/json-output.md).
+
 ### Disable auto-continue countdown
 
 By default, when npq detects only warnings (no errors), it automatically proceeds with installation after a 15-second countdown. To disable this behavior and always require explicit confirmation:

package/bin/npq-hero.js

@@ -51,20 +51,13 @@ RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
       Object.hasOwn(results, 'countErrors') &&
       Object.hasOwn(results, 'countWarnings')
     ) {
-      const {
-        countErrors,
-        countWarnings,
-        countNotEvaluated = 0,
-        useRichFormatting
-      } = results
+      const { countErrors, countWarnings, countNotEvaluated = 0, useRichFormatting } = results
       const hasFindings = countErrors > 0 || countWarnings > 0
       const hasReportableResults = hasFindings || countNotEvaluated > 0
 
       if (hasReportableResults) {
         console.log()
-        console.log(
-          hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:'
-        )
+        console.log(hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:')
 
         if (useRichFormatting) {
           console.log(results.resultsForPrettyPrint)

package/bin/npq.js

@@ -15,171 +15,182 @@ const cliPrompt = require('../lib/helpers/cliPrompt.js')
 const { reportResults } = require('../lib/helpers/reportResults')
 const { Spinner } = require('../lib/helpers/cliSpinner')
 const { promiseThrottleHelper } = require('../lib/helpers/promiseThrottler')
+const { createJsonOutput } = require('../lib/helpers/jsonOutput')
+const { runJsonCli, writeInvalidJsonInvocation } = require('../lib/jsonCli')
 const RegistryConfig = require('../lib/helpers/registryConfig')
 const RegistryClient = require('../lib/helpers/registryClient')
 
 const debug = util.debuglog('npq')
 
-const cliArgs = CliParser.parseArgsFull()
-const auditOnly = cliArgs.dryRun || !cliArgs.installSubcommandExplicit
-const isInteractive = cliSupport.isInteractiveTerminal() && !cliArgs.plain
-const spinner = isInteractive ? new Spinner({ text: 'Initiating...' }) : null
+const jsonRequested = process.argv.slice(2).includes('--json')
+const jsonOutput = jsonRequested ? createJsonOutput() : null
+let cliArgs
 
-if (spinner) {
-  spinner.start()
+try {
+  cliArgs = CliParser.parseArgsFull()
+} catch (error) {
+  if (!jsonRequested) throw error
+  writeInvalidJsonInvocation(jsonOutput)
+  process.exitCode = 2
 }
 
-let registryClient
+if (cliArgs && cliArgs.json) {
+  runJsonCli(cliArgs, { output: jsonOutput })
+} else if (cliArgs) {
+  const auditOnly = cliArgs.dryRun || !cliArgs.installSubcommandExplicit
+  const isInteractive = cliSupport.isInteractiveTerminal() && !cliArgs.plain
+  const spinner = isInteractive ? new Spinner({ text: 'Initiating...' }) : null
 
-RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
-  .then((registryConfig) => {
-    registryClient = new RegistryClient(registryConfig)
-  })
-  .then(() => {
-    if (cliArgs.packages.length === 0) {
-      debug('\nNo packages specified, using project packages from package.json')
-      return getProjectPackages()
-    }
+  if (spinner) {
+    spinner.start()
+  }
 
-    return cliArgs.packages
-  })
-  .then((packages) => {
-    if (packages.error) {
-      console.log()
-      CliParser.exit({
-        errorCode: packages.error.code || -1,
-        message: packages.message,
-        spinner
-      })
-    }
+  let registryClient
 
-    const marshall = new Marshall({
-      pkgs: packages,
-      registryClient,
-      progressManager: spinner,
-      promiseThrottleHelper
+  Promise.resolve()
+    .then(() => RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] }))
+    .then((registryConfig) => {
+      registryClient = new RegistryClient(registryConfig)
     })
+    .then(() => {
+      if (cliArgs.packages.length === 0) {
+        debug('\nNo packages specified, using project packages from package.json')
+        return getProjectPackages()
+      }
 
-    return marshall.process()
-  })
-  .then((marshallResults) => {
-    if (spinner) {
-      spinner.stop()
-    }
-
-    const results = reportResults(marshallResults, { plain: cliArgs.plain })
-    if (
-      results &&
-      Object.hasOwn(results, 'countErrors') &&
-      Object.hasOwn(results, 'countWarnings')
-    ) {
-      const {
-        countErrors,
-        countWarnings,
-        countNotEvaluated = 0,
-        useRichFormatting
-      } = results
-      const hasFindings = countErrors > 0 || countWarnings > 0
-      const hasReportableResults = hasFindings || countNotEvaluated > 0
-
-      if (hasReportableResults) {
+      return cliArgs.packages
+    })
+    .then((packages) => {
+      if (packages.error) {
         console.log()
-        console.log(
-          hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:'
-        )
-
-        if (useRichFormatting) {
-          console.log(results.resultsForPrettyPrint)
-          console.log(results.summaryForPrettyPrint)
-        } else {
-          console.log(results.resultsForPlainTextPrint)
-          console.log(results.summaryForPlainTextPrint)
-        }
+        CliParser.exit({
+          errorCode: packages.error.code || -1,
+          message: packages.message,
+          spinner
+        })
       }
 
-      return {
-        anyIssues: hasFindings,
-        countErrors,
-        countWarnings,
-        countNotEvaluated
-      }
-    }
-    return undefined
-  })
-  .then((result) => {
-    if (auditOnly) {
-      const auditFailed = result && (result.countErrors > 0 || result.countWarnings > 0)
-      CliParser.exit({
-        errorCode: auditFailed ? 1 : 0,
-        spinner
+      const marshall = new Marshall({
+        pkgs: packages,
+        registryClient,
+        progressManager: spinner,
+        promiseThrottleHelper
       })
+
+      return marshall.process()
+    })
+    .then((marshallResults) => {
+      if (spinner) {
+        spinner.stop()
+      }
+
+      const results = reportResults(marshallResults, { plain: cliArgs.plain })
+      if (
+        results &&
+        Object.hasOwn(results, 'countErrors') &&
+        Object.hasOwn(results, 'countWarnings')
+      ) {
+        const { countErrors, countWarnings, countNotEvaluated = 0, useRichFormatting } = results
+        const hasFindings = countErrors > 0 || countWarnings > 0
+        const hasReportableResults = hasFindings || countNotEvaluated > 0
+
+        if (hasReportableResults) {
+          console.log()
+          console.log(hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:')
+
+          if (useRichFormatting) {
+            console.log(results.resultsForPrettyPrint)
+            console.log(results.summaryForPrettyPrint)
+          } else {
+            console.log(results.resultsForPlainTextPrint)
+            console.log(results.summaryForPlainTextPrint)
+          }
+        }
+
+        return {
+          anyIssues: hasFindings,
+          countErrors,
+          countWarnings,
+          countNotEvaluated
+        }
+      }
       return undefined
-    }
-
-    if (result && result.countErrors > 0) {
-      console.log()
-      return cliPrompt.prompt({
-        name: 'install',
-        message: 'Continue install ?',
-        default: false
-      })
-    } else {
-      if (result && result.countWarnings > 0) {
+    })
+    .then((result) => {
+      if (auditOnly) {
+        const auditFailed = result && (result.countErrors > 0 || result.countWarnings > 0)
+        CliParser.exit({
+          errorCode: auditFailed ? 1 : 0,
+          spinner
+        })
+        return undefined
+      }
+
+      if (result && result.countErrors > 0) {
         console.log()
-        // Check if auto-continue is disabled via CLI flag or environment variable
-        if (cliArgs.disableAutoContinue) {
-          return cliPrompt.prompt({
+        return cliPrompt.prompt({
+          name: 'install',
+          message: 'Continue install ?',
+          default: false
+        })
+      } else {
+        if (result && result.countWarnings > 0) {
+          console.log()
+          // Check if auto-continue is disabled via CLI flag or environment variable
+          if (cliArgs.disableAutoContinue) {
+            return cliPrompt.prompt({
+              name: 'install',
+              message: 'Continue install ?',
+              default: false
+            })
+          }
+          return cliPrompt.autoContinue({
             name: 'install',
-            message: 'Continue install ?',
-            default: false
+            message: 'Auto-continue with install in... ',
+            timeInSeconds: 15
           })
         }
-        return cliPrompt.autoContinue({
-          name: 'install',
-          message: 'Auto-continue with install in... ',
-          timeInSeconds: 15
-        })
       }
-    }
 
-    return { install: true }
-  })
-  .then((status) => {
-    if (
-      status &&
-      Object.prototype.hasOwnProperty.call(status, 'install') &&
-      status.install === true
-    ) {
-      return pkgMgr.process(cliArgs.packageManager)
-    }
-  })
-  .then((exitCode) => {
-    if (typeof exitCode === 'number') {
-      process.exitCode = exitCode
-    }
-  })
-  .catch((error) => {
-    // Ensure errorCode is always a number
-    let errorCode = -1
-    if (typeof error.code === 'number') {
-      errorCode = error.code
-    } else if (error.code === 'ABORT_ERR') {
-      errorCode = 1
-    } else if (error.code === 'USER_ABORT') {
-      errorCode = error.exitCode || 1
-    }
+      return { install: true }
+    })
+    .then((status) => {
+      if (
+        status &&
+        Object.prototype.hasOwnProperty.call(status, 'install') &&
+        status.install === true
+      ) {
+        return pkgMgr.process(cliArgs.packageManager)
+      }
+    })
+    .then((exitCode) => {
+      if (typeof exitCode === 'number') {
+        process.exitCode = exitCode
+      }
+    })
+    .catch((error) => {
+      // Ensure errorCode is always a number
+      let errorCode = -1
+      if (typeof error.code === 'number') {
+        errorCode = error.code
+      } else if (error.code === 'ABORT_ERR') {
+        errorCode = 1
+      } else if (error.code === 'USER_ABORT') {
+        errorCode = error.exitCode || 1
+      }
+
+      CliParser.exit({
+        errorCode,
+        message: error.message || 'An error occurred',
+        spinner
+      })
+    })
 
+  // attach event handler for CTRL+C
+  process.on('SIGINT', () => {
     CliParser.exit({
-      errorCode,
-      message: error.message || 'An error occurred',
+      errorCode: 0,
       spinner
     })
   })
-
-// attach event handler for CTRL+C
-process.on('SIGINT', () => {
-  CliParser.exit({
-    errorCode: 0,
-    spinner
-  })
-})
+}

package/lib/cli.js

@@ -2,6 +2,7 @@
 
 const { parseArgs } = require('node:util')
 const npa = require('npm-package-arg')
+const { parseJsonRegistryPackageSpec } = require('./helpers/jsonPackageSpec')
 const pkg = require('../package.json')
 const { parsePackageManagerArguments } = require('./helpers/packageManagerArgumentParser')
 
@@ -45,7 +46,7 @@ class CliParser {
     process.exit(exitCode)
   }
 
-  static _extractPackagesFromPositionals(positionals, earlyExitNoInstall = false) {
+  static _extractPackagesFromPositionals(positionals, earlyExitNoInstall = false, json = false) {
     let packages = []
     if (positionals.length > 0) {
       const command = positionals[0]
@@ -61,7 +62,7 @@ class CliParser {
 
     // Parse and normalize packages
     return packages.map((pkg) => {
-      const parsedPackage = npa(pkg)
+      const parsedPackage = json ? parseJsonRegistryPackageSpec(pkg) : npa(pkg)
       const versionModifier = parsedPackage.fetchSpec === '*' ? 'latest' : parsedPackage.fetchSpec
       return `${parsedPackage.name}@${versionModifier}`
     })
@@ -71,6 +72,7 @@ class CliParser {
     const options = {
       'dry-run': { type: 'boolean' },
       plain: { type: 'boolean' },
+      json: { type: 'boolean' },
       packageManager: { type: 'string' },
       pkgMgr: { type: 'string' },
       'disable-auto-continue': { type: 'boolean' },
@@ -102,6 +104,7 @@ Commands:
 Options:
       --dry-run               Run checks only, don't install
       --plain                 Force non-rich text output
+      --json                  Emit JSON and never install
       --packageManager        Package Manager to use (default: npm)
       --pkgMgr                Alias for packageManager
       --disable-auto-continue Disable auto-continue countdown, always prompt
@@ -129,7 +132,11 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
     }
 
     // Process install command and packages
-    const normalizedPackages = this._extractPackagesFromPositionals(positionals)
+    const normalizedPackages = this._extractPackagesFromPositionals(
+      positionals,
+      false,
+      values.json === true
+    )
     const installSubcommandExplicit =
       positionals.length > 0 && this.isInstallSubcommand(positionals[0])
 
@@ -138,6 +145,7 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
       packageManager: process.env.NPQ_PKG_MGR || values.packageManager || values.pkgMgr || 'npm',
       dryRun: values['dry-run'] || false,
       plain: values.plain || false,
+      json: values.json || false,
       disableAutoContinue:
         values['disable-auto-continue'] || process.env.NPQ_DISABLE_AUTO_CONTINUE === 'true',
       registryConfigArgs: this.registryConfigArgs(values),

package/lib/helpers/auditFailure.js

@@ -0,0 +1,25 @@
+'use strict'
+
+const AUDIT_FAILURE_CODES = Object.freeze({
+  INVALID_INPUT: 'INVALID_INPUT',
+  PROJECT_MANIFEST_ERROR: 'PROJECT_MANIFEST_ERROR',
+  PACKAGE_LOOKUP_FAILED: 'PACKAGE_LOOKUP_FAILED',
+  AUDIT_CHECK_FAILED: 'AUDIT_CHECK_FAILED',
+  INTERRUPTED: 'INTERRUPTED',
+  INTERNAL_ERROR: 'INTERNAL_ERROR'
+})
+
+const knownCodes = new Set(Object.values(AUDIT_FAILURE_CODES))
+
+function createAuditFailure(code, message, context = {}) {
+  const failure = {
+    code: knownCodes.has(code) ? code : AUDIT_FAILURE_CODES.INTERNAL_ERROR,
+    message: String(message)
+  }
+
+  if (context.package) failure.package = String(context.package)
+  if (context.marshall) failure.marshall = String(context.marshall)
+  return failure
+}
+
+module.exports = { AUDIT_FAILURE_CODES, createAuditFailure }

package/lib/helpers/jsonOutput.js

@@ -0,0 +1,24 @@
+'use strict'
+
+function createJsonOutput(write = (value, callback) => process.stdout.write(value, callback)) {
+  let written = false
+
+  return {
+    write(report, onComplete) {
+      if (written) return false
+      written = true
+      const serialized = `${JSON.stringify(report)}\n`
+      if (typeof onComplete === 'function') {
+        write(serialized, onComplete)
+      } else {
+        write(serialized)
+      }
+      return true
+    },
+    hasWritten() {
+      return written
+    }
+  }
+}
+
+module.exports = { createJsonOutput }

package/lib/helpers/jsonPackageSpec.js

@@ -0,0 +1,29 @@
+'use strict'
+
+const npa = require('npm-package-arg')
+
+const JSON_REGISTRY_SPEC_TYPES = new Set(['tag', 'version', 'range'])
+
+function parseJsonRegistryPackageSpec(packageSpec) {
+  try {
+    const parsedPackage = npa(packageSpec)
+    if (!parsedPackage.name || !JSON_REGISTRY_SPEC_TYPES.has(parsedPackage.type)) {
+      throw new Error('Unsupported package spec')
+    }
+
+    return parsedPackage
+  } catch {
+    throw new Error('Invalid JSON package input')
+  }
+}
+
+function isJsonRegistryPackageSpec(packageSpec) {
+  try {
+    parseJsonRegistryPackageSpec(packageSpec)
+    return true
+  } catch {
+    return false
+  }
+}
+
+module.exports = { isJsonRegistryPackageSpec, parseJsonRegistryPackageSpec }

package/lib/helpers/jsonReport.js

@@ -0,0 +1,76 @@
+'use strict'
+
+const pkg = require('../../package.json')
+const { marshallCategories } = require('../marshalls/constants')
+const { createAuditFailure } = require('./auditFailure')
+
+function normalizeMarshallGroup(group = {}) {
+  const findings = []
+
+  for (const value of Object.values(group)) {
+    if (!value || typeof value !== 'object') continue
+    const category = marshallCategories[value.categoryId] || {
+      id: value.categoryId,
+      title: value.categoryId
+    }
+
+    for (const warning of value.warnings || []) {
+      findings.push({
+        severity: 'warning',
+        marshall: value.marshall,
+        category: { id: category.id, title: category.title },
+        message: warning.message
+      })
+    }
+    for (const error of value.errors || []) {
+      findings.push({
+        severity: 'error',
+        marshall: value.marshall,
+        category: { id: category.id, title: category.title },
+        message: error.message
+      })
+    }
+  }
+
+  return findings
+}
+
+function buildJsonReport({
+  packages = [],
+  marshallResults = {},
+  failures = [],
+  version = pkg.version
+} = {}) {
+  const positionalResults = Array.isArray(marshallResults)
+  const packageReports = packages.map((requested, index) => {
+    const results = positionalResults ? marshallResults[index] : marshallResults[requested]
+    return {
+      requested,
+      findings: (results || []).flatMap(normalizeMarshallGroup)
+    }
+  })
+  const findings = packageReports.flatMap((entry) => entry.findings)
+  const errors = findings.filter((item) => item.severity === 'error').length
+  const warnings = findings.filter((item) => item.severity === 'warning').length
+  const status = failures.length > 0 ? 'failed' : errors + warnings > 0 ? 'findings' : 'clean'
+
+  return {
+    schemaVersion: 1,
+    tool: { name: 'npq', version },
+    status,
+    summary: { packagesAudited: packageReports.length, errors, warnings },
+    packages: packageReports,
+    failures: failures.map((failure) =>
+      createAuditFailure(failure.code, failure.message, {
+        package: failure.package,
+        marshall: failure.marshall
+      })
+    )
+  }
+}
+
+function exitCodeForJsonReport(report) {
+  return report.status === 'failed' ? 2 : report.status === 'findings' ? 1 : 0
+}
+
+module.exports = { buildJsonReport, exitCodeForJsonReport }

package/lib/helpers/registryClient.js

@@ -16,8 +16,7 @@ const CAPABILITY = Object.freeze({
 const CAPABILITY_MESSAGE = Object.freeze({
   [CAPABILITY.SIGNING_KEYS]: 'configured registry does not expose signing keys',
   [CAPABILITY.ATTESTATIONS]: 'configured registry does not expose attestations',
-  [CAPABILITY.DOWNLOAD_COUNTS]:
-    'download counts are available only for the public npm registry'
+  [CAPABILITY.DOWNLOAD_COUNTS]: 'download counts are available only for the public npm registry'
 })
 
 class RegistryClient {
@@ -47,11 +46,7 @@ class RegistryClient {
     }
   }
 
-  async requestJson(
-    requestPath,
-    packageSpec,
-    { capability = null, notFoundAsData = false } = {}
-  ) {
+  async requestJson(requestPath, packageSpec, { capability = null, notFoundAsData = false } = {}) {
     const registry = this.registryFor(packageSpec)
     try {
       return await this.fetcher.json(requestPath, this.requestOptions(packageSpec))

package/lib/helpers/registryConfig.js

@@ -3,12 +3,7 @@
 const path = require('node:path')
 const Config = require('@npmcli/config')
 const npmFetch = require('npm-registry-fetch')
-const {
-  definitions,
-  flatten,
-  nerfDarts,
-  shorthands
-} = require('@npmcli/config/lib/definitions')
+const { definitions, flatten, nerfDarts, shorthands } = require('@npmcli/config/lib/definitions')
 const { RegistryError, sanitizeRegistryUrl } = require('./registryErrors')
 
 const DEFAULT_REGISTRY = 'https://registry.npmjs.org/'
@@ -57,8 +52,7 @@ class RegistryConfig {
       }
       return new RegistryConfig(config.flat)
     } catch (error) {
-      const code =
-        error.code === 'ERR_INVALID_AUTH' ? 'EREGISTRYCONFIGAUTH' : 'EREGISTRYCONFIG'
+      const code = error.code === 'ERR_INVALID_AUTH' ? 'EREGISTRYCONFIGAUTH' : 'EREGISTRYCONFIG'
       const message =
         error.code === 'ERR_INVALID_AUTH'
           ? 'Invalid npm registry authentication configuration'

package/lib/helpers/reportResults.js

@@ -230,15 +230,9 @@ function reportResults(marshallResults, { plain = false } = {}) {
             entry.categoryFriendlyName.padEnd(maxTextLength, ' ')
           )
           const iconRich = styleText(['cyan'], '○')
-          const wrappedMessage = wrapTextWithIndent(
-            entry.message,
-            maxMessageWidth,
-            indentString
-          )
-          resultsForPrettyPrint +=
-            `\n ${prefixRich} ${iconRich} ${topicRich} ${separatorRich} ${wrappedMessage} `
-          resultsForPlainTextPrint +=
-            `\n  NOT EVALUATED: ${entry.categoryFriendlyName} - ${entry.message}`
+          const wrappedMessage = wrapTextWithIndent(entry.message, maxMessageWidth, indentString)
+          resultsForPrettyPrint += `\n ${prefixRich} ${iconRich} ${topicRich} ${separatorRich} ${wrappedMessage} `
+          resultsForPlainTextPrint += `\n  NOT EVALUATED: ${entry.categoryFriendlyName} - ${entry.message}`
         })
       })
     }
@@ -256,16 +250,11 @@ function reportResults(marshallResults, { plain = false } = {}) {
           terminalWidth - getDisplayLength(' │ ℹ Suggested older release · ') - 2
         )
         const detailWidth = Math.max(20, terminalWidth - getDisplayLength(' │   ') - 2)
-        const wrappedHeadline = wrapTextWithIndent(
-          headline,
-          headlineWidth,
-          suggestionIndent
-        )
+        const wrappedHeadline = wrapTextWithIndent(headline, headlineWidth, suggestionIndent)
         const wrappedDetail = wrapTextWithIndent(detail, detailWidth, suggestionIndent)
 
         resultsForPrettyPrint += `\n ${prefixRich}`
-        resultsForPrettyPrint +=
-          `\n ${prefixRich} ${iconRich} ${labelRich} ${separatorRich} ${wrappedHeadline}`
+        resultsForPrettyPrint += `\n ${prefixRich} ${iconRich} ${labelRich} ${separatorRich} ${wrappedHeadline}`
         resultsForPrettyPrint += `\n${suggestionIndent}${wrappedDetail}`
 
         resultsForPlainTextPrint +=

package/lib/helpers/versionAge.js

@@ -23,12 +23,7 @@ function findAlternativeVersion({
   requestedVersion,
   now = Date.now()
 }) {
-  if (
-    !packageInfo ||
-    !packageInfo.versions ||
-    !packageInfo.time ||
-    !semver.valid(targetVersion)
-  ) {
+  if (!packageInfo || !packageInfo.versions || !packageInfo.time || !semver.valid(targetVersion)) {
     return null
   }
 
@@ -49,9 +44,7 @@ function findAlternativeVersion({
     })
     .filter(
       ({ publishedAt, ageDays }) =>
-        typeof publishedAt === 'string' &&
-        ageDays !== null &&
-        ageDays > MAX_VERSION_RECENCY_DAYS
+        typeof publishedAt === 'string' && ageDays !== null && ageDays > MAX_VERSION_RECENCY_DAYS
     )
     .sort((left, right) => semver.rcompare(left.version, right.version))
 

package/lib/jsonAudit.js

@@ -0,0 +1,71 @@
+'use strict'
+
+const { getProjectPackages } = require('./helpers/sourcePackages')
+const Marshall = require('./marshall')
+const { promiseThrottleHelper } = require('./helpers/promiseThrottler')
+const { buildJsonReport } = require('./helpers/jsonReport')
+const { AUDIT_FAILURE_CODES, createAuditFailure } = require('./helpers/auditFailure')
+const { isJsonRegistryPackageSpec } = require('./helpers/jsonPackageSpec')
+const RegistryConfig = require('./helpers/registryConfig')
+const RegistryClient = require('./helpers/registryClient')
+
+async function runJsonAudit(cliArgs, dependencies = {}) {
+  const getPackages = dependencies.getProjectPackages || getProjectPackages
+  const MarshallClass = dependencies.Marshall || Marshall
+  const throttle = dependencies.promiseThrottleHelper || promiseThrottleHelper
+  const RegistryConfigClass = dependencies.RegistryConfig || RegistryConfig
+  const RegistryClientClass = dependencies.RegistryClient || RegistryClient
+  let packages = cliArgs.packages || []
+  const failures = []
+
+  try {
+    if (packages.length === 0) {
+      const projectPackages = await getPackages()
+      if (projectPackages && projectPackages.error) {
+        return buildJsonReport({
+          failures: [
+            createAuditFailure(
+              AUDIT_FAILURE_CODES.PROJECT_MANIFEST_ERROR,
+              'Unable to read project package.json'
+            )
+          ]
+        })
+      }
+      packages = projectPackages
+    }
+
+    if (!packages.every(isJsonRegistryPackageSpec)) {
+      return buildJsonReport({
+        failures: [
+          createAuditFailure(
+            AUDIT_FAILURE_CODES.INVALID_INPUT,
+            'Invalid package or option argument'
+          )
+        ]
+      })
+    }
+
+    const registryConfig = await RegistryConfigClass.load({
+      argv: cliArgs.registryConfigArgs || []
+    })
+    const registryClient = new RegistryClientClass(registryConfig)
+    const marshall = new MarshallClass({
+      pkgs: packages,
+      progressManager: null,
+      promiseThrottleHelper: throttle,
+      registryClient,
+      preserveRequestOrder: true,
+      suppressOutput: true,
+      onAuditFailure: (failure) => failures.push(failure)
+    })
+    const marshallResults = await marshall.process()
+    return buildJsonReport({ packages, marshallResults, failures })
+  } catch {
+    failures.push(
+      createAuditFailure(AUDIT_FAILURE_CODES.INTERNAL_ERROR, 'JSON audit could not complete')
+    )
+    return buildJsonReport({ packages, failures })
+  }
+}
+
+module.exports = { runJsonAudit }

package/lib/jsonCli.js

@@ -0,0 +1,61 @@
+'use strict'
+
+const { createJsonOutput } = require('./helpers/jsonOutput')
+const { buildJsonReport, exitCodeForJsonReport } = require('./helpers/jsonReport')
+const { AUDIT_FAILURE_CODES, createAuditFailure } = require('./helpers/auditFailure')
+const { runJsonAudit } = require('./jsonAudit')
+
+function writeInvalidJsonInvocation(output = createJsonOutput()) {
+  const report = buildJsonReport({
+    failures: [
+      createAuditFailure(AUDIT_FAILURE_CODES.INVALID_INPUT, 'Invalid package or option argument')
+    ]
+  })
+  output.write(report)
+  return report
+}
+
+async function runJsonCli(cliArgs, dependencies = {}) {
+  const output = dependencies.output || createJsonOutput()
+  const processTarget = dependencies.processTarget || process
+  const audit = dependencies.runJsonAudit || runJsonAudit
+  const getExitCode = dependencies.exitCodeForJsonReport || exitCodeForJsonReport
+  let interrupted = false
+  let interruptedReport
+
+  const interrupt = () => {
+    interrupted = true
+    interruptedReport = buildJsonReport({
+      packages: cliArgs.packages || [],
+      failures: [createAuditFailure(AUDIT_FAILURE_CODES.INTERRUPTED, 'Audit interrupted')]
+    })
+    output.write(interruptedReport, () => {
+      processTarget.exit(2)
+    })
+  }
+
+  processTarget.once('SIGINT', interrupt)
+  let report
+  try {
+    report = await audit(cliArgs)
+  } catch {
+    report = buildJsonReport({
+      packages: cliArgs.packages || [],
+      failures: [
+        createAuditFailure(AUDIT_FAILURE_CODES.INTERNAL_ERROR, 'JSON audit could not complete')
+      ]
+    })
+  } finally {
+    processTarget.removeListener('SIGINT', interrupt)
+  }
+
+  if (interrupted) {
+    return interruptedReport
+  }
+
+  output.write(report)
+  processTarget.exitCode = getExitCode(report)
+  return report
+}
+
+module.exports = { runJsonCli, writeInvalidJsonInvocation }

package/lib/marshall.js

@@ -11,14 +11,15 @@ class Marshall {
     options = options || {}
     this.pkgs = options.pkgs || null
     this.registryClient =
-      options.registryClient ||
-      options.packageRepoUtils?.registryClient ||
-      RegistryClient.public()
+      options.registryClient || options.packageRepoUtils?.registryClient || RegistryClient.public()
     this.packageRepoUtils =
-      options.packageRepoUtils ||
-      new PackageRepoUtils({ registryClient: this.registryClient })
+      options.packageRepoUtils || new PackageRepoUtils({ registryClient: this.registryClient })
     this.progressManager = options.progressManager || null
     this.promiseThrottleHelper = options.promiseThrottleHelper || null
+    this.preserveRequestOrder = options.preserveRequestOrder === true
+    this.suppressOutput = options.suppressOutput === true
+    this.onAuditFailure =
+      typeof options.onAuditFailure === 'function' ? options.onAuditFailure : null
   }
 
   async process() {
@@ -57,6 +58,7 @@ class Marshall {
       this.progressManager.stop()
     }
 
+    if (this.preserveRequestOrder) return res
     return promiseResultsPerPackage
   }
 
@@ -67,7 +69,10 @@ class Marshall {
       packageRepoUtils: packageRepoUtils,
       registryClient: this.registryClient
     }
-    return Marshalls.tasks(config, this.progressManager)
+    return Marshalls.tasks(config, this.progressManager, {
+      onAuditFailure: this.onAuditFailure,
+      suppressOutput: this.suppressOutput
+    })
   }
 
   createPackageVersionMaps(packages) {

package/lib/marshalls/baseMarshall.js

@@ -9,7 +9,7 @@ const { marshallCategories } = require('./constants')
 
 class BaseMarshall {
   constructor(options) {
-    this.debug = util.debuglog('npq')
+    this.debug = options.suppressOutput ? () => {} : util.debuglog('npq')
     this.packageRepoUtils = options.packageRepoUtils
     this.registryClient = options.registryClient
     this.categoryId = marshallCategories.PackageHealth.id

package/lib/marshalls/index.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const { AUDIT_FAILURE_CODES, createAuditFailure } = require('../helpers/auditFailure')
 const { RegistryError } = require('../helpers/registryErrors')
 
 class Marshalls {
@@ -22,7 +23,8 @@ class Marshalls {
 
     const config = {
       packageRepoUtils: options.packageRepoUtils,
-      registryClient: options.registryClient
+      registryClient: options.registryClient,
+      suppressOutput: options.suppressOutput === true
     }
 
     const marshallTasks = marshalls.reduce((prev, curr) => {
@@ -36,6 +38,7 @@ class Marshalls {
 
       return prev.concat({
         title: marshall.title(),
+        name: marshall.name,
         categoryId: marshall.categoryId,
         execute: async (options) => {
           const ctx = {
@@ -61,7 +64,11 @@ class Marshalls {
    * @param {Object} [progressManager] - Optional progress manager for displaying audit progress updates
    * @returns {Promise<Array<Object>>} Array of marshall results containing audit findings for each package
    */
-  static async tasks(options, progressManager) {
+  static async tasks(
+    options,
+    progressManager,
+    { onAuditFailure = null, suppressOutput = false } = {}
+  ) {
     const marshallResults = []
 
     // @TODO handle throw error because fetch didn't work due to network issues
@@ -78,7 +85,23 @@ class Marshalls {
     //     hostname: 'registry.npmjs.org'
     //   }
     // }
-    const packagesDataList = await Marshalls.warmUpPackagesCache(options)
+    let packagesDataList
+    try {
+      packagesDataList = await Marshalls.warmUpPackagesCache(options)
+    } catch (error) {
+      if (!onAuditFailure) throw error
+
+      for (const pkg of options.pkgs) {
+        onAuditFailure(
+          createAuditFailure(
+            AUDIT_FAILURE_CODES.PACKAGE_LOOKUP_FAILED,
+            'Unable to retrieve package metadata',
+            { package: pkg.packageString }
+          )
+        )
+      }
+      return marshallResults
+    }
 
     // handle error in case we get just one package and it is not found
     // if (packagesDataList && packagesDataList.length === 1) {
@@ -123,7 +146,8 @@ class Marshalls {
     if (packagesToProcess.length > 0) {
       const marshallTasks = await Marshalls.buildMarshallTasks(marshalls, {
         packageRepoUtils: options.packageRepoUtils,
-        registryClient: options.registryClient
+        registryClient: options.registryClient,
+        suppressOutput
       })
 
       for (const marshall of marshallTasks) {
@@ -134,10 +158,23 @@ class Marshalls {
           })
           marshallResults.push(res.marshalls)
         } catch (error) {
-          if (error instanceof RegistryError) {
-            throw error
+          if (!onAuditFailure) {
+            if (error instanceof RegistryError) {
+              throw error
+            }
+            console.error(`Error running task ${marshall.title}:`, error)
+            continue
+          }
+
+          for (const pkg of options.pkgs) {
+            onAuditFailure(
+              createAuditFailure(
+                AUDIT_FAILURE_CODES.AUDIT_CHECK_FAILED,
+                'Audit check could not complete',
+                { package: pkg.packageString, marshall: marshall.name }
+              )
+            )
           }
-          console.error(`Error running task ${marshall.title}:`, error)
         }
       }
     }

package/lib/marshalls/signatures.marshall.js

@@ -50,10 +50,7 @@ class Marshall extends BaseMarshall {
       if (error instanceof NotEvaluated || error instanceof RegistryError) {
         throw error
       }
-      if (
-        error.message &&
-        error.message.includes('but the corresponding public key has expired')
-      ) {
+      if (error.message && error.message.includes('but the corresponding public key has expired')) {
         throw new Warning('Package is signed with an expired key')
       }
       throw new Warning(`Unable to verify package signature on registry: ${error.message}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npq",
-  "version": "3.23.2",
+  "version": "3.24.0",
   "description": "marshall your npm/npm package installs with high quality and class 🎖",
   "bin": {
     "npq": "./bin/npq.js",
@@ -27,6 +27,7 @@
     "bin/",
     "data/",
     "lib/",
+    "schema/",
     "scripts/"
   ],
   "author": {
@@ -52,6 +53,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.32.0",
+    "ajv": "^8.20.0",
     "eslint": "^9.32.0",
     "eslint-plugin-n": "^17.21.3",
     "eslint-plugin-security": "^3.0.1",

package/schema/npq-output-v1.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/lirantal/npq/main/schema/npq-output-v1.schema.json",
+  "title": "npq JSON audit output v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "tool", "status", "summary", "packages", "failures"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "tool": { "$ref": "#/$defs/tool" },
+    "status": { "enum": ["clean", "findings", "failed"] },
+    "summary": { "$ref": "#/$defs/summary" },
+    "packages": { "type": "array", "items": { "$ref": "#/$defs/package" } },
+    "failures": { "type": "array", "items": { "$ref": "#/$defs/failure" } }
+  },
+  "$defs": {
+    "tool": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "const": "npq" },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["packagesAudited", "errors", "warnings"],
+      "properties": {
+        "packagesAudited": { "type": "integer", "minimum": 0 },
+        "errors": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requested", "findings"],
+      "properties": {
+        "requested": { "type": "string", "minLength": 1 },
+        "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["severity", "marshall", "category", "message"],
+      "properties": {
+        "severity": { "enum": ["warning", "error"] },
+        "marshall": { "type": "string", "minLength": 1 },
+        "category": { "$ref": "#/$defs/category" },
+        "message": { "type": "string" }
+      }
+    },
+    "category": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "enum": [
+            "INVALID_INPUT",
+            "PROJECT_MANIFEST_ERROR",
+            "PACKAGE_LOOKUP_FAILED",
+            "AUDIT_CHECK_FAILED",
+            "INTERRUPTED",
+            "INTERNAL_ERROR"
+          ]
+        },
+        "message": { "type": "string", "minLength": 1 },
+        "package": { "type": "string", "minLength": 1 },
+        "marshall": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}