@socketsecurity/cli 0.2.1 → 0.4.0

package/README.md

@@ -1,5 +1,6 @@
 # Socket CLI
 
+[![Socket Badge](https://socket.dev/api/badge/npm/pkg/@socketsecurity/cli)](https://socket.dev/npm/package/@socketsecurity/cli)
 [![npm version](https://img.shields.io/npm/v/@socketsecurity/cli.svg?style=flat)](https://www.npmjs.com/package/@socketsecurity/cli)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/SocketDev/eslint-config)
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
@@ -22,7 +23,15 @@ socket report view QXU8PmK7LfH608RAwfIKdbcHgwEd_ZeWJ9QEGv05FJUQ
 ## Commands
 
 * `socket info <package@version>` - looks up issues for a package
-* `socket report create <path(s)-to-folder-or-file>` - uploads the specified `package.json` and/or `package-lock.json` to create a report on [socket.dev](https://socket.dev/). If only one of a `package.json`/`package-lock.json` has been specified, the other will be automatically found and uploaded if it exists
+
+* `socket report create <path(s)-to-folder-or-file>` - creates a report on [socket.dev](https://socket.dev/)
+
+  Uploads the specified `package.json` and lock files and, if any folder is specified, the ones found in there. Also includes the complementary `package.json` and lock file to any specified. Currently `package-lock.json` and `yarn.lock` are supported.
+
+  Supports globbing such as `**/package.json`.
+
+  Ignores any file specified in your project's `.gitignore`, the `projectIgnorePaths` in your project's [`socket.yml`](https://docs.socket.dev/docs/socket-yml) and on top of that has a sensible set of [default ignores](https://www.npmjs.com/package/ignore-by-default)
+
 * `socket report view <report-id>` - looks up issues and scores from a report
 
 ## Flags
@@ -36,6 +45,11 @@ socket report view QXU8PmK7LfH608RAwfIKdbcHgwEd_ZeWJ9QEGv05FJUQ
 * `--json` - outputs result as json which you can then pipe into [`jq`](https://stedolan.github.io/jq/) and other tools
 * `--markdown` - outputs result as markdown which you can then copy into an issue, PR or even chat
 
+## Strictness flags
+
+* `--all` - by default only `high` and `critical` issues are included, by setting this flag all issues will be included
+* `--strict` - when set, exits with an error code if report result is deemed unhealthy
+
 ### Other flags
 
 * `--dry-run` - like all CLI tools that perform an action should have, we have a dry run flag. Eg. `socket report create` supports running the command without actually uploading anything
@@ -43,6 +57,10 @@ socket report view QXU8PmK7LfH608RAwfIKdbcHgwEd_ZeWJ9QEGv05FJUQ
 * `--help` - prints the help for the current command. All CLI tools should have this flag
 * `--version` - prints the version of the tool. All CLI tools should have this flag
 
+## Configuration files
+
+The CLI reads and uses data from a [`socket.yml` file](https://docs.socket.dev/docs/socket-yml) in the folder you run it in. It supports the version 2 of the `socket.yml` file format and makes use of the `projectIgnorePaths` to excludes files when creating a report.
+
 ## Environment variables
 
 * `SOCKET_SECURITY_API_KEY` - if set, this will be used as the API-key

package/cli.js

@@ -37,6 +37,7 @@ try {
   } else if (err instanceof InputError) {
     errorTitle = 'Invalid input'
     errorMessage = err.message
+    errorBody = err.body
   } else if (err instanceof Error) {
     errorTitle = 'Unexpected error'
     errorMessage = messageWithCauses(err)

package/lib/commands/info/index.js

@@ -7,8 +7,9 @@ import ora from 'ora'
 import { handleApiCall, handleUnsuccessfulApiResponse } from '../../utils/api-helpers.js'
 import { ChalkOrMarkdown } from '../../utils/chalk-markdown.js'
 import { InputError } from '../../utils/errors.js'
-import { getSeveritySummary } from '../../utils/format-issues.js'
+import { getSeverityCount, formatSeverityCount } from '../../utils/format-issues.js'
 import { printFlagList } from '../../utils/formatting.js'
+import { objectSome } from '../../utils/misc.js'
 import { setupSdk } from '../../utils/sdk.js'
 
 /** @type {import('../../utils/meow-with-subcommands').CliSubcommand} */
@@ -18,32 +19,44 @@ export const info = {
     const name = parentName + ' info'
 
     const input = setupCommand(name, info.description, argv, importMeta)
-    const result = input && await fetchPackageData(input.pkgName, input.pkgVersion)
+    const packageData = input && await fetchPackageData(input.pkgName, input.pkgVersion, input)
 
-    if (result) {
-      formatPackageDataOutput(result.data, { name, ...input })
+    if (packageData) {
+      formatPackageDataOutput(packageData, { name, ...input })
     }
   }
 }
 
 // Internal functions
 
+/**
+ * @typedef CommandContext
+ * @property {boolean} includeAllIssues
+ * @property {boolean} outputJson
+ * @property {boolean} outputMarkdown
+ * @property {string} pkgName
+ * @property {string} pkgVersion
+ * @property {boolean} strict
+ */
+
 /**
  * @param {string} name
  * @param {string} description
  * @param {readonly string[]} argv
  * @param {ImportMeta} importMeta
- * @returns {void|{ outputJson: boolean, outputMarkdown: boolean, pkgName: string, pkgVersion: string }}
+ * @returns {void|CommandContext}
  */
- function setupCommand (name, description, argv, importMeta) {
+function setupCommand (name, description, argv, importMeta) {
   const cli = meow(`
     Usage
       $ ${name} <name>
 
     Options
       ${printFlagList({
+        '--all': 'Include all issues',
         '--json': 'Output result as json',
         '--markdown': 'Output result as markdown',
+        '--strict': 'Exits with an error code if any matching issues are found',
       }, 6)}
 
     Examples
@@ -54,6 +67,10 @@ export const info = {
     description,
     importMeta,
     flags: {
+      all: {
+        type: 'boolean',
+        default: false,
+      },
       json: {
         type: 'boolean',
         alias: 'j',
@@ -64,12 +81,18 @@ export const info = {
         alias: 'm',
         default: false,
       },
+      strict: {
+        type: 'boolean',
+        default: false,
+      },
     }
   })
 
   const {
+    all: includeAllIssues,
     json: outputJson,
     markdown: outputMarkdown,
+    strict,
   } = cli.flags
 
   if (cli.input.length > 1) {
@@ -97,19 +120,28 @@ export const info = {
   }
 
   return {
+    includeAllIssues,
     outputJson,
     outputMarkdown,
     pkgName,
-    pkgVersion
+    pkgVersion,
+    strict,
   }
 }
 
+/**
+ * @typedef PackageData
+ * @property {import('@socketsecurity/sdk').SocketSdkReturnType<'getIssuesByNPMPackage'>["data"]} data
+ * @property {Record<import('../../utils/format-issues').SocketIssue['severity'], number>} severityCount
+ */
+
 /**
  * @param {string} pkgName
  * @param {string} pkgVersion
- * @returns {Promise<void|import('@socketsecurity/sdk').SocketSdkReturnType<'getIssuesByNPMPackage'>>}
+ * @param {Pick<CommandContext, 'includeAllIssues' | 'strict'>} context
+ * @returns {Promise<void|PackageData>}
  */
-async function fetchPackageData (pkgName, pkgVersion) {
+async function fetchPackageData (pkgName, pkgVersion, { includeAllIssues, strict }) {
   const socketSdk = await setupSdk()
   const spinner = ora(`Looking up data for version ${pkgVersion} of ${pkgName}`).start()
   const result = await handleApiCall(socketSdk.getIssuesByNPMPackage(pkgName, pkgVersion), spinner, 'looking up package')
@@ -120,32 +152,40 @@ async function fetchPackageData (pkgName, pkgVersion) {
 
   // Conclude the status of the API call
 
-  const issueSummary = getSeveritySummary(result.data)
-  spinner.succeed(`Found ${issueSummary || 'no'} issues for version ${pkgVersion} of ${pkgName}`)
+  const severityCount = getSeverityCount(result.data, includeAllIssues ? undefined : 'high')
+
+  if (objectSome(severityCount)) {
+    const issueSummary = formatSeverityCount(severityCount)
+    spinner[strict ? 'fail' : 'succeed'](`Package has these issues: ${issueSummary}`)
+  } else {
+    spinner.succeed('Package has no issues')
+  }
 
-  return result
+  return {
+    data: result.data,
+    severityCount,
+  }
 }
 
 /**
- * @param {import('@socketsecurity/sdk').SocketSdkReturnType<'getIssuesByNPMPackage'>["data"]} data
- * @param {{ name: string, outputJson: boolean, outputMarkdown: boolean, pkgName: string, pkgVersion: string }} context
+ * @param {PackageData} packageData
+ * @param {{ name: string } & CommandContext} context
  * @returns {void}
  */
- function formatPackageDataOutput (data, { name, outputJson, outputMarkdown, pkgName, pkgVersion }) {
-  // If JSON, output and return...
-
+ function formatPackageDataOutput ({ data, severityCount }, { name, outputJson, outputMarkdown, pkgName, pkgVersion, strict }) {
   if (outputJson) {
     console.log(JSON.stringify(data, undefined, 2))
-    return
-  }
-
-  // ...else do the CLI / Markdown output dance
+  } else {
+    const format = new ChalkOrMarkdown(!!outputMarkdown)
+    const url = `https://socket.dev/npm/package/${pkgName}/overview/${pkgVersion}`
 
-  const format = new ChalkOrMarkdown(!!outputMarkdown)
-  const url = `https://socket.dev/npm/package/${pkgName}/overview/${pkgVersion}`
+    console.log('\nDetailed info on socket.dev: ' + format.hyperlink(`${pkgName} v${pkgVersion}`, url, { fallbackToUrl: true }))
+    if (!outputMarkdown) {
+      console.log(chalk.dim('\nOr rerun', chalk.italic(name), 'using the', chalk.italic('--json'), 'flag to get full JSON output'))
+    }
+  }
 
-  console.log('\nDetailed info on socket.dev: ' + format.hyperlink(`${pkgName} v${pkgVersion}`, url, { fallbackToUrl: true }))
-  if (!outputMarkdown) {
-    console.log(chalk.dim('\nOr rerun', chalk.italic(name), 'using the', chalk.italic('--json'), 'flag to get full JSON output'))
+  if (strict && objectSome(severityCount)) {
+    process.exit(1)
   }
 }

package/lib/commands/report/create.js

@@ -1,20 +1,21 @@
 /* eslint-disable no-console */
 
-import { stat } from 'node:fs/promises'
 import path from 'node:path'
 
+import { betterAjvErrors } from '@apideck/better-ajv-errors'
+import { readSocketConfig, SocketValidationError } from '@socketsecurity/config'
 import meow from 'meow'
 import ora from 'ora'
 import { ErrorWithCause } from 'pony-cause'
 
+import { fetchReportData, formatReportDataOutput } from './view.js'
 import { handleApiCall, handleUnsuccessfulApiResponse } from '../../utils/api-helpers.js'
 import { ChalkOrMarkdown, logSymbols } from '../../utils/chalk-markdown.js'
 import { InputError } from '../../utils/errors.js'
 import { printFlagList } from '../../utils/formatting.js'
 import { createDebugLogger } from '../../utils/misc.js'
+import { getPackageFiles } from '../../utils/path-resolve.js'
 import { setupSdk } from '../../utils/sdk.js'
-import { isErrnoException } from '../../utils/type-helpers.js'
-import { fetchReportData, formatReportDataOutput } from './view.js'
 
 /** @type {import('../../utils/meow-with-subcommands').CliSubcommand} */
 export const create = {
@@ -26,23 +27,26 @@ export const create = {
 
     if (input) {
       const {
+        config,
         cwd,
         debugLog,
         dryRun,
+        includeAllIssues,
         outputJson,
         outputMarkdown,
         packagePaths,
+        strict,
         view,
       } = input
 
-      const result = input && await createReport(packagePaths, { cwd, debugLog, dryRun })
+      const result = input && await createReport(packagePaths, { config, cwd, debugLog, dryRun })
 
       if (result && view) {
         const reportId = result.data.id
-        const reportResult = input && await fetchReportData(reportId)
+        const reportData = input && await fetchReportData(reportId, { includeAllIssues, strict })
 
-        if (reportResult) {
-          formatReportDataOutput(reportResult.data, { name, outputJson, outputMarkdown, reportId })
+        if (reportData) {
+          formatReportDataOutput(reportData, { includeAllIssues, name, outputJson, outputMarkdown, reportId, strict })
         }
       } else if (result) {
         formatReportCreationOutput(result.data, { outputJson, outputMarkdown })
@@ -53,30 +57,57 @@ export const create = {
 
 // Internal functions
 
+/**
+ * @typedef CommandContext
+ * @property {import('@socketsecurity/config').SocketYml|undefined} config
+ * @property {string} cwd
+ * @property {typeof console.error} debugLog
+ * @property {boolean} dryRun
+ * @property {boolean} includeAllIssues
+ * @property {boolean} outputJson
+ * @property {boolean} outputMarkdown
+ * @property {string[]} packagePaths
+ * @property {boolean} strict
+ * @property {boolean} view
+ */
+
 /**
  * @param {string} name
  * @param {string} description
  * @param {readonly string[]} argv
  * @param {ImportMeta} importMeta
- * @returns {Promise<void|{ cwd: string, debugLog: typeof console.error, dryRun: boolean, outputJson: boolean, outputMarkdown: boolean, packagePaths: string[], view: boolean }>}
+ * @returns {Promise<void|CommandContext>}
  */
 async function setupCommand (name, description, argv, importMeta) {
   const cli = meow(`
     Usage
       $ ${name} <paths-to-package-folders-and-files>
 
+    Uploads the specified "package.json" and lock files and, if any folder is
+    specified, the ones found in there. Also includes the complementary
+    "package.json" and lock file to any specified. Currently "package-lock.json"
+    and "yarn.lock" are supported.
+
+    Supports globbing such as "**/package.json".
+
+    Ignores any file specified in your project's ".gitignore", your project's
+    "socket.yml" file's "projectIgnorePaths" and also has a sensible set of
+    default ignores from the "ignore-by-default" module.
+
     Options
       ${printFlagList({
+        '--all': 'Include all issues',
         '--debug': 'Output debug information',
         '--dry-run': 'Only output what will be done without actually doing it',
         '--json': 'Output result as json',
         '--markdown': 'Output result as markdown',
+        '--strict': 'Exits with an error code if any matching issues are found',
         '--view': 'Will wait for and return the created report'
       }, 6)}
 
     Examples
       $ ${name} .
-      $ ${name} ../package-lock.json
+      $ ${name} '**/package.json'
       $ ${name} /path/to/a/package.json /path/to/another/package.json
       $ ${name} . --view --json
   `, {
@@ -84,6 +115,10 @@ async function setupCommand (name, description, argv, importMeta) {
     description,
     importMeta,
     flags: {
+      all: {
+        type: 'boolean',
+        default: false,
+      },
       debug: {
         type: 'boolean',
         alias: 'd',
@@ -103,6 +138,10 @@ async function setupCommand (name, description, argv, importMeta) {
         alias: 'm',
         default: false,
       },
+      strict: {
+        type: 'boolean',
+        default: false,
+      },
       view: {
         type: 'boolean',
         alias: 'v',
@@ -112,9 +151,11 @@ async function setupCommand (name, description, argv, importMeta) {
   })
 
   const {
+    all: includeAllIssues,
     dryRun,
     json: outputJson,
     markdown: outputMarkdown,
+    strict,
     view,
   } = cli.flags
 
@@ -125,27 +166,53 @@ async function setupCommand (name, description, argv, importMeta) {
 
   const debugLog = createDebugLogger(dryRun || cli.flags.debug)
 
+  // TODO: Allow setting a custom cwd and/or configFile path?
   const cwd = process.cwd()
-  const packagePaths = await resolvePackagePaths(cwd, cli.input)
+  const absoluteConfigPath = path.join(cwd, 'socket.yml')
+
+  const config = await readSocketConfig(absoluteConfigPath)
+    .catch(/** @param {unknown} cause */ cause => {
+      if (cause && typeof cause === 'object' && cause instanceof SocketValidationError) {
+        // Inspired by workbox-build: https://github.com/GoogleChrome/workbox/blob/95f97a207fd51efb3f8a653f6e3e58224183a778/packages/workbox-build/src/lib/validate-options.ts#L68-L71
+        const betterErrors = betterAjvErrors({
+          basePath: 'config',
+          data: cause.data,
+          errors: cause.validationErrors,
+          // @ts-ignore
+          schema: cause.schema,
+        })
+        throw new InputError(
+          'The socket.yml config is not valid',
+          betterErrors.map((err) => `[${err.path}] ${err.message}.${err.suggestion ? err.suggestion : ''}`).join('\n')
+        )
+      } else {
+        throw new ErrorWithCause('Failed to read socket.yml config', { cause })
+      }
+    })
+
+  const packagePaths = await getPackageFiles(cwd, cli.input, config, debugLog)
 
   return {
+    config,
     cwd,
     debugLog,
     dryRun,
+    includeAllIssues,
     outputJson,
     outputMarkdown,
     packagePaths,
+    strict,
     view,
   }
 }
 
 /**
  * @param {string[]} packagePaths
- * @param {{ cwd: string, debugLog: typeof console.error, dryRun: boolean }} context
+ * @param {Pick<CommandContext, 'config' | 'cwd' | 'debugLog' | 'dryRun'>} context
  * @returns {Promise<void|import('@socketsecurity/sdk').SocketSdkReturnType<'createReport'>>}
  */
-async function createReport (packagePaths, { cwd, debugLog, dryRun }) {
-  debugLog(`${logSymbols.info} Uploading:`, packagePaths.join(`\n${logSymbols.info} Uploading:`))
+async function createReport (packagePaths, { config, cwd, debugLog, dryRun }) {
+  debugLog('Uploading:', packagePaths.join(`\n${logSymbols.info} Uploading: `))
 
   if (dryRun) {
     return
@@ -153,7 +220,8 @@ async function createReport (packagePaths, { cwd, debugLog, dryRun }) {
 
   const socketSdk = await setupSdk()
   const spinner = ora(`Creating report with ${packagePaths.length} package files`).start()
-  const result = await handleApiCall(socketSdk.createReportFromFilePaths(packagePaths, cwd), spinner, 'creating report')
+  const apiCall = socketSdk.createReportFromFilePaths(packagePaths, cwd, config?.issueRules)
+  const result = await handleApiCall(apiCall, spinner, 'creating report')
 
   if (result.success === false) {
     return handleUnsuccessfulApiResponse(result, spinner)
@@ -168,7 +236,7 @@ async function createReport (packagePaths, { cwd, debugLog, dryRun }) {
 
 /**
  * @param {import('@socketsecurity/sdk').SocketSdkReturnType<'createReport'>["data"]} data
- * @param {{ outputJson: boolean, outputMarkdown: boolean }} context
+ * @param {Pick<CommandContext, 'outputJson' | 'outputMarkdown'>} context
  * @returns {void}
  */
 function formatReportCreationOutput (data, { outputJson, outputMarkdown }) {
@@ -181,113 +249,3 @@ function formatReportCreationOutput (data, { outputJson, outputMarkdown }) {
 
   console.log('\nNew report: ' + format.hyperlink(data.id, data.url, { fallbackToUrl: true }))
 }
-
-// TODO: Add globbing support with support for ignoring, as a "./**/package.json" in a project also traverses eg. node_modules
-/**
- * Takes paths to folders and/or package.json / package-lock.json files and resolves to package.json + package-lock.json pairs (where feasible)
- *
- * @param {string} cwd
- * @param {string[]} inputPaths
- * @returns {Promise<string[]>}
- * @throws {InputError}
- */
-async function resolvePackagePaths (cwd, inputPaths) {
-  const packagePathLookups = inputPaths.map(async (filePath) => {
-    const packagePath = await resolvePackagePath(cwd, filePath)
-    return findComplementaryPackageFile(packagePath)
-  })
-
-  const packagePaths = await Promise.all(packagePathLookups)
-
-  const uniquePackagePaths = new Set(packagePaths.flat())
-
-  return [...uniquePackagePaths]
-}
-
-/**
- * Resolves a package.json / package-lock.json path from a relative folder / file path
- *
- * @param {string} cwd
- * @param {string} inputPath
- * @returns {Promise<string>}
- * @throws {InputError}
- */
-async function resolvePackagePath (cwd, inputPath) {
-  const filePath = path.resolve(cwd, inputPath)
-  /** @type {string|undefined} */
-  let filePathAppended
-
-  try {
-    const fileStat = await stat(filePath)
-
-    if (fileStat.isDirectory()) {
-      filePathAppended = path.resolve(filePath, 'package.json')
-    }
-  } catch (err) {
-    if (isErrnoException(err) && err.code === 'ENOENT') {
-      throw new InputError(`Expected '${inputPath}' to point to an existing file or directory`)
-    }
-    throw new ErrorWithCause('Failed to resolve path to package.json', { cause: err })
-  }
-
-  if (filePathAppended) {
-    /** @type {import('node:fs').Stats} */
-    let filePathAppendedStat
-
-    try {
-      filePathAppendedStat = await stat(filePathAppended)
-    } catch (err) {
-      if (isErrnoException(err) && err.code === 'ENOENT') {
-        throw new InputError(`Expected directory '${inputPath}' to contain a package.json file`)
-      }
-      throw new ErrorWithCause('Failed to resolve package.json in directory', { cause: err })
-    }
-
-    if (!filePathAppendedStat.isFile()) {
-      throw new InputError(`Expected '${filePathAppended}' to be a file`)
-    }
-
-    return filePathAppended
-  }
-
-  return filePath
-}
-
-/**
- * Finds any complementary file to a package.json or package-lock.json
- *
- * @param {string} packagePath
- * @returns {Promise<string[]>}
- * @throws {InputError}
- */
-async function findComplementaryPackageFile (packagePath) {
-  const basename = path.basename(packagePath)
-  const dirname = path.dirname(packagePath)
-
-  if (basename === 'package-lock.json') {
-    // We need the package file as well
-    return [
-      packagePath,
-      path.resolve(dirname, 'package.json')
-    ]
-  }
-
-  if (basename === 'package.json') {
-    const lockfilePath = path.resolve(dirname, 'package-lock.json')
-    try {
-      const lockfileStat = await stat(lockfilePath)
-      if (lockfileStat.isFile()) {
-        return [packagePath, lockfilePath]
-      }
-    } catch (err) {
-      if (isErrnoException(err) && err.code === 'ENOENT') {
-        return [packagePath]
-      }
-      throw new ErrorWithCause(`Unexpected error when finding a lockfile for '${packagePath}'`, { cause: err })
-    }
-
-    throw new InputError(`Encountered a non-file at lockfile path '${lockfilePath}'`)
-  }
-
-  throw new InputError(`Expected '${packagePath}' to point to a package.json or package-lock.json or to a folder containing a package.json`)
-}

package/lib/commands/report/index.js

@@ -1,6 +1,6 @@
-import { meowWithSubcommands } from '../../utils/meow-with-subcommands.js'
 import { create } from './create.js'
 import { view } from './view.js'
+import { meowWithSubcommands } from '../../utils/meow-with-subcommands.js'
 
 const description = 'Project report related commands'
 

package/lib/commands/report/view.js

@@ -7,7 +7,7 @@ import ora from 'ora'
 import { handleApiCall, handleUnsuccessfulApiResponse } from '../../utils/api-helpers.js'
 import { ChalkOrMarkdown } from '../../utils/chalk-markdown.js'
 import { InputError } from '../../utils/errors.js'
-import { getSeveritySummary } from '../../utils/format-issues.js'
+import { getSeverityCount, formatSeverityCount } from '../../utils/format-issues.js'
 import { printFlagList } from '../../utils/formatting.js'
 import { setupSdk } from '../../utils/sdk.js'
 
@@ -18,22 +18,32 @@ export const view = {
     const name = parentName + ' view'
 
     const input = setupCommand(name, view.description, argv, importMeta)
-    const result = input && await fetchReportData(input.reportId)
+    const result = input && await fetchReportData(input.reportId, input)
 
     if (result) {
-      formatReportDataOutput(result.data, { name, ...input })
+      formatReportDataOutput(result, { name, ...input })
     }
   }
 }
 
 // Internal functions
 
+// TODO: Share more of the flag setup inbetween the commands
+/**
+ * @typedef CommandContext
+ * @property {boolean} includeAllIssues
+ * @property {boolean} outputJson
+ * @property {boolean} outputMarkdown
+ * @property {string} reportId
+ * @property {boolean} strict
+ */
+
 /**
  * @param {string} name
  * @param {string} description
  * @param {readonly string[]} argv
  * @param {ImportMeta} importMeta
- * @returns {void|{ outputJson: boolean, outputMarkdown: boolean, reportId: string }}
+ * @returns {void|CommandContext}
  */
 function setupCommand (name, description, argv, importMeta) {
   const cli = meow(`
@@ -42,8 +52,10 @@ function setupCommand (name, description, argv, importMeta) {
 
     Options
       ${printFlagList({
+        '--all': 'Include all issues',
         '--json': 'Output result as json',
         '--markdown': 'Output result as markdown',
+        '--strict': 'Exits with an error code if report result is deemed unhealthy',
       }, 6)}
 
     Examples
@@ -53,9 +65,8 @@ function setupCommand (name, description, argv, importMeta) {
     description,
     importMeta,
     flags: {
-      debug: {
+      all: {
         type: 'boolean',
-        alias: 'd',
         default: false,
       },
       json: {
@@ -68,14 +79,20 @@ function setupCommand (name, description, argv, importMeta) {
         alias: 'm',
         default: false,
       },
+      strict: {
+        type: 'boolean',
+        default: false,
+      },
     }
   })
 
   // Extract the input
 
   const {
+    all: includeAllIssues,
     json: outputJson,
     markdown: outputMarkdown,
+    strict,
   } = cli.flags
 
   const [reportId, ...extraInput] = cli.input
@@ -92,17 +109,24 @@ function setupCommand (name, description, argv, importMeta) {
   }
 
   return {
+    includeAllIssues,
     outputJson,
     outputMarkdown,
     reportId,
+    strict,
   }
 }
 
+/**
+ * @typedef {import('@socketsecurity/sdk').SocketSdkReturnType<'getReport'>["data"]} ReportData
+ */
+
 /**
  * @param {string} reportId
- * @returns {Promise<void|import('@socketsecurity/sdk').SocketSdkReturnType<'getReport'>>}
+ * @param {Pick<CommandContext, 'includeAllIssues' | 'strict'>} context
+ * @returns {Promise<void|ReportData>}
  */
-export async function fetchReportData (reportId) {
+export async function fetchReportData (reportId, { includeAllIssues, strict }) {
   // Do the API call
 
   const socketSdk = await setupSdk()
@@ -115,32 +139,42 @@ export async function fetchReportData (reportId) {
 
   // Conclude the status of the API call
 
-  const issueSummary = getSeveritySummary(result.data.issues)
-  spinner.succeed(`Report contains ${issueSummary || 'no'} issues`)
+  if (strict) {
+    if (result.data.healthy) {
+      spinner.succeed('Report result is healthy and great!')
+    } else {
+      spinner.fail('Report result deemed unhealthy for project')
+    }
+  } else if (result.data.healthy === false) {
+    const severityCount = getSeverityCount(result.data.issues, includeAllIssues ? undefined : 'high')
+    const issueSummary = formatSeverityCount(severityCount)
+    spinner.succeed(`Report has these issues: ${issueSummary}`)
+  } else {
+    spinner.succeed('Report has no issues')
+  }
 
-  return result
+  return result.data
 }
 
 /**
- * @param {import('@socketsecurity/sdk').SocketSdkReturnType<'getReport'>["data"]} data
- * @param {{ name: string, outputJson: boolean, outputMarkdown: boolean, reportId: string }} context
+ * @param {ReportData} data
+ * @param {{ name: string } & CommandContext} context
  * @returns {void}
  */
-export function formatReportDataOutput (data, { name, outputJson, outputMarkdown, reportId }) {
-  // If JSON, output and return...
-
+export function formatReportDataOutput (data, { name, outputJson, outputMarkdown, reportId, strict }) {
   if (outputJson) {
     console.log(JSON.stringify(data, undefined, 2))
-    return
-  }
-
-  // ...else do the CLI / Markdown output dance
+  } else {
+    const format = new ChalkOrMarkdown(!!outputMarkdown)
+    const url = `https://socket.dev/npm/reports/${encodeURIComponent(reportId)}`
 
-  const format = new ChalkOrMarkdown(!!outputMarkdown)
-  const url = `https://socket.dev/npm/reports/${encodeURIComponent(reportId)}`
+    console.log('\nDetailed info on socket.dev: ' + format.hyperlink(reportId, url, { fallbackToUrl: true }))
+    if (!outputMarkdown) {
+      console.log(chalk.dim('\nOr rerun', chalk.italic(name), 'using the', chalk.italic('--json'), 'flag to get full JSON output'))
+    }
+  }
 
-  console.log('\nDetailed info on socket.dev: ' + format.hyperlink(reportId, url, { fallbackToUrl: true }))
-  if (!outputMarkdown) {
-    console.log(chalk.dim('\nOr rerun', chalk.italic(name), 'using the', chalk.italic('--json'), 'flag to get full JSON output'))
+  if (strict && data.healthy === false) {
+    process.exit(1)
   }
 }

package/lib/utils/errors.js

@@ -1,2 +1,14 @@
 export class AuthError extends Error {}
-export class InputError extends Error {}
+
+export class InputError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [body]
+   */
+  constructor (message, body) {
+    super(message)
+
+    /** @type {string|undefined} */
+    this.body = body
+  }
+}

package/lib/utils/format-issues.js

@@ -1,15 +1,43 @@
 /** @typedef {import('@socketsecurity/sdk').SocketSdkReturnType<'getIssuesByNPMPackage'>['data']} SocketIssueList */
 /** @typedef {SocketIssueList[number]['value'] extends infer U | undefined ? U : never} SocketIssue */
 
-import { stringJoinWithSeparateFinalSeparator } from './misc.js'
+import { pick, stringJoinWithSeparateFinalSeparator } from './misc.js'
+
+const SEVERITIES_BY_ORDER = /** @type {const} */ ([
+  'critical',
+  'high',
+  'middle',
+  'low',
+])
+
+/**
+ * @param {SocketIssue['severity']|undefined} lowestToInclude
+ * @returns {Array<SocketIssue['severity']>}
+ */
+ function getDesiredSeverities (lowestToInclude) {
+  /** @type {Array<SocketIssue['severity']>} */
+  const result = []
+
+  for (const severity of SEVERITIES_BY_ORDER) {
+    result.push(severity)
+    if (severity === lowestToInclude) {
+      break
+    }
+  }
+
+  return result
+}
 
 /**
  * @param {SocketIssueList} issues
+ * @param {SocketIssue['severity']} [lowestToInclude]
  * @returns {Record<SocketIssue['severity'], number>}
  */
-function getSeverityCount (issues) {
-  /** @type {Record<SocketIssue['severity'], number>} */
-  const severityCount = { low: 0, middle: 0, high: 0, critical: 0 }
+export function getSeverityCount (issues, lowestToInclude) {
+  const severityCount = pick(
+    { low: 0, middle: 0, high: 0, critical: 0 },
+    getDesiredSeverities(lowestToInclude)
+  )
 
   for (const issue of issues) {
     const value = issue.value
@@ -27,18 +55,18 @@ function getSeverityCount (issues) {
 }
 
 /**
- * @param {SocketIssueList} issues
+ * @param {Record<SocketIssue['severity'], number>} severityCount
  * @returns {string}
  */
-export function getSeveritySummary (issues) {
-  const severityCount = getSeverityCount(issues)
+export function formatSeverityCount (severityCount) {
+  /** @type {string[]} */
+  const summary = []
 
-  const issueSummary = stringJoinWithSeparateFinalSeparator([
-    severityCount.critical ? severityCount.critical + ' critical' : undefined,
-    severityCount.high ? severityCount.high + ' high' : undefined,
-    severityCount.middle ? severityCount.middle + ' middle' : undefined,
-    severityCount.low ? severityCount.low + ' low' : undefined,
-  ])
+  for (const severity of SEVERITIES_BY_ORDER) {
+    if (severityCount[severity]) {
+      summary.push(`${severityCount[severity]} ${severity}`)
+    }
+  }
 
-  return issueSummary
+  return stringJoinWithSeparateFinalSeparator(summary)
 }

package/lib/utils/misc.js

@@ -1,13 +1,14 @@
+import { logSymbols } from './chalk-markdown.js'
+
 /**
  * @param {boolean|undefined} printDebugLogs
  * @returns {typeof console.error}
  */
 export function createDebugLogger (printDebugLogs) {
-  if (printDebugLogs) {
+  return printDebugLogs
     // eslint-disable-next-line no-console
-    return console.error.bind(console)
-  }
-  return () => {}
+    ? (...params) => console.error(logSymbols.info, ...params)
+    : () => {}
 }
 
 /**
@@ -26,3 +27,36 @@ export function stringJoinWithSeparateFinalSeparator (list, separator = ' and ')
 
   return values.join(', ') + separator + finalValue
 }
+
+/**
+ * Returns a new object with only the specified keys from the input object
+ *
+ * @template {Record<string,any>} T
+ * @template {keyof T} K
+ * @param {T} input
+ * @param {K[]|ReadonlyArray<K>} keys
+ * @returns {Pick<T, K>}
+ */
+export function pick (input, keys) {
+  /** @type {Partial<Pick<T, K>>} */
+  const result = {}
+
+  for (const key of keys) {
+    result[key] = input[key]
+  }
+
+  return /** @type {Pick<T, K>} */ (result)
+}
+
+/**
+ * @param {Record<string,any>} obj
+ * @returns {boolean}
+ */
+export function objectSome (obj) {
+  for (const key in obj) {
+    if (obj[key]) {
+      return true
+    }
+  }
+  return false
+}

package/lib/utils/path-resolve.js

@@ -0,0 +1,152 @@
+import { stat } from 'node:fs/promises'
+import path from 'node:path'
+
+import { globby } from 'globby'
+import ignore from 'ignore'
+// @ts-ignore This package provides no types
+import { directories } from 'ignore-by-default'
+import { ErrorWithCause } from 'pony-cause'
+
+import { InputError } from './errors.js'
+import { isErrnoException } from './type-helpers.js'
+
+/** @type {readonly string[]} */
+const SUPPORTED_LOCKFILES = [
+  'package-lock.json',
+  'yarn.lock',
+]
+
+/**
+ * There are a lot of possible folders that we should not be looking in and "ignore-by-default" helps us with defining those
+ *
+ * @type {readonly string[]}
+ */
+const ignoreByDefault = directories()
+
+/** @type {readonly string[]} */
+const GLOB_IGNORE = [
+  ...ignoreByDefault.map(item => '**/' + item)
+]
+
+/**
+ * Resolves package.json and lockfiles from (globbed) input paths, applying relevant ignores
+ *
+ * @param {string} cwd The working directory to use when resolving paths
+ * @param {string[]} inputPaths A list of paths to folders, package.json files and/or recognized lockfiles. Supports globs.
+ * @param {import('@socketsecurity/config').SocketYml|undefined} config
+ * @param {typeof console.error} debugLog
+ * @returns {Promise<string[]>}
+ * @throws {InputError}
+ */
+export async function getPackageFiles (cwd, inputPaths, config, debugLog) {
+  const entries = await globby(inputPaths, {
+    absolute: true,
+    cwd,
+    expandDirectories: false,
+    gitignore: true,
+    ignore: [...GLOB_IGNORE],
+    markDirectories: true,
+    onlyFiles: false,
+    unique: true,
+  })
+
+  debugLog(`Globbed resolved ${inputPaths.length} paths to ${entries.length} paths:`, entries)
+
+  const packageFiles = await mapGlobResultToFiles(entries)
+
+  debugLog(`Mapped ${entries.length} entries to ${packageFiles.length} files:`, packageFiles)
+
+  const includedPackageFiles = config?.projectIgnorePaths?.length
+    ? ignore()
+      .add(config.projectIgnorePaths)
+      .filter(packageFiles.map(item => path.relative(cwd, item)))
+      .map(item => path.resolve(cwd, item))
+    : packageFiles
+
+  return includedPackageFiles
+}
+
+/**
+ * Takes paths to folders, package.json and/or recognized lock files and resolves them to package.json + lockfile pairs (where possible)
+ *
+ * @param {string[]} entries
+ * @returns {Promise<string[]>}
+ * @throws {InputError}
+ */
+export async function mapGlobResultToFiles (entries) {
+  const packageFiles = await Promise.all(entries.map(mapGlobEntryToFiles))
+
+  const uniquePackageFiles = [...new Set(packageFiles.flat())]
+
+  return uniquePackageFiles
+}
+
+/**
+ * Takes a single path to a folder, package.json or a recognized lock file and resolves to a package.json + lockfile pair (where possible)
+ *
+ * @param {string} entry
+ * @returns {Promise<string[]>}
+ * @throws {InputError}
+ */
+export async function mapGlobEntryToFiles (entry) {
+  /** @type {string|undefined} */
+  let pkgFile
+  /** @type {string|undefined} */
+  let lockFile
+
+  if (entry.endsWith('/')) {
+    // If the match is a folder and that folder contains a package.json file, then include it
+    const filePath = path.resolve(entry, 'package.json')
+    pkgFile = await fileExists(filePath) ? filePath : undefined
+  } else if (path.basename(entry) === 'package.json') {
+    // If the match is a package.json file, then include it
+    pkgFile = entry
+  } else if (SUPPORTED_LOCKFILES.includes(path.basename(entry))) {
+    // If the match is a lock file, include both it and the corresponding package.json file
+    lockFile = entry
+    pkgFile = path.resolve(path.dirname(entry), 'package.json')
+  }
+
+  // If we will include a package.json file but don't already have a corresponding lockfile, then look for one
+  if (!lockFile && pkgFile) {
+    const pkgDir = path.dirname(pkgFile)
+
+    for (const name of SUPPORTED_LOCKFILES) {
+      const lockFileAlternative = path.resolve(pkgDir, name)
+      if (await fileExists(lockFileAlternative)) {
+        lockFile = lockFileAlternative
+        break
+      }
+    }
+  }
+
+  if (pkgFile && lockFile) {
+    return [pkgFile, lockFile]
+  }
+
+  return pkgFile ? [pkgFile] : []
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+export async function fileExists (filePath) {
+  /** @type {import('node:fs').Stats} */
+  let pathStat
+
+  try {
+    pathStat = await stat(filePath)
+  } catch (err) {
+    if (isErrnoException(err) && err.code === 'ENOENT') {
+      return false
+    }
+    throw new ErrorWithCause('Error while checking if file exists', { cause: err })
+  }
+
+  if (!pathStat.isFile()) {
+    throw new InputError(`Expected '${filePath}' to be a file`)
+  }
+
+  return true
+}

package/lib/utils/sdk.js

@@ -1,4 +1,8 @@
-import { SocketSdk } from '@socketsecurity/sdk'
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { SocketSdk, createUserAgentFromPkgJson } from '@socketsecurity/sdk'
 import isInteractive from 'is-interactive'
 import prompts from 'prompts'
 
@@ -34,11 +38,14 @@ export async function setupSdk () {
       https: new HttpsProxyAgent({ proxy: process.env['SOCKET_SECURITY_API_PROXY'] }),
     }
   }
+  const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json')
+  const packageJson = await readFile(packageJsonPath, 'utf8')
 
   /** @type {import('@socketsecurity/sdk').SocketSdkOptions} */
   const sdkOptions = {
     agent,
     baseUrl: process.env['SOCKET_SECURITY_API_BASE_URL'],
+    userAgent: createUserAgentFromPkgJson(JSON.parse(packageJson))
   }
 
   return new SocketSdk(apiKey || '', sdkOptions)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "CLI tool for Socket.dev",
   "homepage": "http://github.com/SocketDev/socket-cli-js",
   "repository": {
@@ -32,7 +32,6 @@
     "check:tsc": "tsc",
     "check:type-coverage": "type-coverage --detail --strict --at-least 95 --ignore-files 'test/*'",
     "check": "run-p -c --aggregate-output check:*",
-    "generate-types": "node lib/utils/generate-types.js > lib/types/api.d.ts",
     "prepare": "husky install",
     "test:mocha": "c8 --reporter=lcov --reporter text mocha 'test/**/*.spec.js'",
     "test-ci": "run-s test:*",
@@ -42,36 +41,47 @@
     "@socketsecurity/eslint-config": "^1.0.0",
     "@tsconfig/node14": "^1.0.3",
     "@types/chai": "^4.3.3",
+    "@types/chai-as-promised": "^7.1.5",
     "@types/mocha": "^10.0.0",
+    "@types/mock-fs": "^4.13.1",
     "@types/node": "^14.18.31",
     "@types/prompts": "^2.4.1",
     "@types/update-notifier": "^6.0.1",
-    "@typescript-eslint/eslint-plugin": "^5.44.0",
-    "@typescript-eslint/parser": "^5.44.0",
+    "@typescript-eslint/eslint-plugin": "^5.48.2",
+    "@typescript-eslint/parser": "^5.48.2",
     "c8": "^7.12.0",
     "chai": "^4.3.6",
+    "chai-as-promised": "^7.1.1",
     "dependency-check": "^5.0.0-7",
-    "eslint": "^8.28.0",
+    "eslint": "^8.32.0",
     "eslint-config-standard": "^17.0.0",
     "eslint-config-standard-jsx": "^11.0.0",
-    "eslint-import-resolver-typescript": "^3.5.2",
-    "eslint-plugin-import": "^2.26.0",
+    "eslint-import-resolver-typescript": "^3.5.3",
+    "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-jsdoc": "^39.5.0",
-    "eslint-plugin-n": "^15.5.1",
+    "eslint-plugin-n": "^15.6.1",
     "eslint-plugin-promise": "^6.1.1",
-    "eslint-plugin-react": "^7.31.11",
+    "eslint-plugin-react": "^7.32.1",
     "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-unicorn": "^45.0.2",
     "husky": "^8.0.1",
     "installed-check": "^6.0.5",
     "mocha": "^10.0.0",
+    "mock-fs": "^5.2.0",
+    "nock": "^13.3.0",
     "npm-run-all2": "^6.0.2",
     "type-coverage": "^2.24.1",
-    "typescript": "~4.9.3"
+    "typescript": "~4.9.4"
   },
   "dependencies": {
-    "@socketsecurity/sdk": "^0.4.0",
+    "@apideck/better-ajv-errors": "^0.3.6",
+    "@socketsecurity/config": "^2.0.0",
+    "@socketsecurity/sdk": "^0.5.2",
     "chalk": "^5.1.2",
+    "globby": "^13.1.3",
     "hpagent": "^1.2.0",
+    "ignore": "^5.2.1",
+    "ignore-by-default": "^2.1.0",
     "is-interactive": "^2.0.0",
     "is-unicode-supported": "^1.3.0",
     "meow": "^11.0.0",