feat(scan): unit suffixes for reachability timeout/memory limits (1.1.123, Coana 15.5.0)

--reach-analysis-timeout and --reach-analysis-memory-limit now accept unit
suffixes (s/m/h for duration, MB/GB for memory, case-insensitive). Coana owns
the canonical parsing, so the CLI forwards the raw string verbatim instead of
coercing to a number. A thin local validator gives fast errors before the Coana
binary is spawned.

Empty or zero-magnitude values are omitted when forwarding so Coana applies its
own defaults, preserving the prior numeric-0 sentinel. Bare numbers keep working
but are no longer documented. Bumps the bundled Coana CLI to 15.5.0, whose parser
handles these units.

Author: mtorp

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.1.123](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.123) - 2026-06-18
+
+### Added
+- `socket scan create --reach` and `socket scan reach` now accept unit suffixes on `--reach-analysis-timeout` (`s`, `m`, `h` — e.g. `90s`, `10m`, `1h`) and `--reach-analysis-memory-limit` (`MB`, `GB` — e.g. `512MB`, `8GB`). Plain numbers keep working as before.
+
+### Changed
+- Updated the Coana CLI to v `15.5.0`.
+
 ## [1.1.122](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.122) - 2026-06-17
 
 ### Changed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "socket",
-  "version": "1.1.122",
+  "version": "1.1.123",
   "description": "CLI for Socket.dev",
   "homepage": "https://github.com/SocketDev/socket-cli",
   "license": "MIT",
@@ -96,7 +96,7 @@
     "@babel/preset-typescript": "7.27.1",
     "@babel/runtime": "7.28.4",
     "@biomejs/biome": "2.2.4",
-    "@coana-tech/cli": "15.4.6",
+    "@coana-tech/cli": "15.5.0",
     "@cyclonedx/cdxgen": "12.1.2",
     "@dotenvx/dotenvx": "1.49.0",
     "@eslint/compat": "1.3.2",

pnpm-lock.yaml

@@ -52,8 +52,8 @@ export async function handleCi(autoManifest: boolean): Promise<void> {
     pullRequest: 0,
     reach: {
       excludePaths: [],
-      reachAnalysisMemoryLimit: 0,
-      reachAnalysisTimeout: 0,
+      reachAnalysisMemoryLimit: '',
+      reachAnalysisTimeout: '',
       reachConcurrency: 1,
       reachContinueOnAnalysisErrors: false,
       reachContinueOnInstallErrors: false,

src/commands/ci/handle-ci.mts

@@ -8,6 +8,12 @@ import { assertValidExcludePaths } from './exclude-paths.mts'
 import { handleCreateNewScan } from './handle-create-new-scan.mts'
 import { outputCreateNewScan } from './output-create-new-scan.mts'
 import { excludePathsFlag, reachabilityFlags } from './reachability-flags.mts'
+import {
+  REACH_ANALYSIS_MEMORY_LIMIT_HELP,
+  REACH_ANALYSIS_TIMEOUT_HELP,
+  isValidReachAnalysisMemoryLimit,
+  isValidReachAnalysisTimeout,
+} from './reachability-units.mts'
 import { suggestOrgSlug } from './suggest-org-slug.mts'
 import { suggestTarget } from './suggest_target.mts'
 import { validateReachabilityTarget } from './validate-reachability-target.mts'
@@ -284,8 +290,8 @@ async function run(
     tmp: boolean
     // Reachability flags.
     reach: boolean
-    reachAnalysisMemoryLimit: number
-    reachAnalysisTimeout: number
+    reachAnalysisMemoryLimit: string
+    reachAnalysisTimeout: string
     reachConcurrency: number
     reachContinueOnAnalysisErrors: boolean
     reachContinueOnInstallErrors: boolean
@@ -572,6 +578,18 @@ async function run(
       message: 'Reachability analysis flags require --reach to be enabled',
       fail: 'add --reach flag to use --reach-* options',
     },
+    {
+      nook: true,
+      test: !reach || isValidReachAnalysisTimeout(reachAnalysisTimeout),
+      message: `The --reach-analysis-timeout must be ${REACH_ANALYSIS_TIMEOUT_HELP}`,
+      fail: `invalid value "${reachAnalysisTimeout}"`,
+    },
+    {
+      nook: true,
+      test: !reach || isValidReachAnalysisMemoryLimit(reachAnalysisMemoryLimit),
+      message: `The --reach-analysis-memory-limit must be ${REACH_ANALYSIS_MEMORY_LIMIT_HELP}`,
+      fail: `invalid value "${reachAnalysisMemoryLimit}"`,
+    },
     {
       nook: true,
       test: !reach || reachTargetValidation.isValid,
@@ -633,8 +651,8 @@ async function run(
           })
         : undefined,
       excludePaths,
-      reachAnalysisMemoryLimit: Number(reachAnalysisMemoryLimit),
-      reachAnalysisTimeout: Number(reachAnalysisTimeout),
+      reachAnalysisMemoryLimit,
+      reachAnalysisTimeout,
       reachConcurrency: Number(reachConcurrency),
       reachContinueOnAnalysisErrors: Boolean(reachContinueOnAnalysisErrors),
       reachContinueOnInstallErrors: Boolean(reachContinueOnInstallErrors),

src/commands/scan/cmd-scan-create.mts

@@ -56,8 +56,8 @@ describe('socket scan create', async () => {
             --workspace         The workspace in the Socket Organization that the repository is in to associate with the full scan.
 
           Reachability Options (when --reach is used)
-            --reach-analysis-memory-limit  The maximum memory in MB to use for the reachability analysis. The default is 8192MB.
-            --reach-analysis-timeout  Set timeout for the reachability analysis. Split analysis runs may cause the total scan time to exceed this timeout significantly.
+            --reach-analysis-memory-limit  The maximum memory for the reachability analysis as a whole number optionally followed by MB or GB (e.g. 512MB, 8GB). The default is 8GB.
+            --reach-analysis-timeout  Set the timeout for the reachability analysis as a whole number optionally followed by s, m or h (e.g. 90s, 10m, 1h). Defaults to 10m. Split analysis runs may cause the total scan time to exceed this timeout significantly.
             --reach-concurrency  Set the maximum number of concurrent reachability analysis runs. It is recommended to choose a concurrency level that ensures each analysis run has at least the --reach-analysis-memory-limit amount of memory available.
             --reach-continue-on-analysis-errors  Continue reachability analysis when errors occur (timeouts, OOM, parse errors, etc.), falling back to precomputed (Tier 2) results. By default, the CLI halts on analysis errors.
             --reach-continue-on-install-errors  Continue reachability analysis when package installation fails, falling back to precomputed (Tier 2) results. By default, the CLI halts on installation errors.

src/commands/scan/cmd-scan-create.test.mts

@@ -6,6 +6,12 @@ import { logger } from '@socketsecurity/registry/lib/logger'
 import { assertValidExcludePaths } from './exclude-paths.mts'
 import { handleScanReach } from './handle-scan-reach.mts'
 import { excludePathsFlag, reachabilityFlags } from './reachability-flags.mts'
+import {
+  REACH_ANALYSIS_MEMORY_LIMIT_HELP,
+  REACH_ANALYSIS_TIMEOUT_HELP,
+  isValidReachAnalysisMemoryLimit,
+  isValidReachAnalysisTimeout,
+} from './reachability-units.mts'
 import { suggestTarget } from './suggest_target.mts'
 import { validateReachabilityTarget } from './validate-reachability-target.mts'
 import constants from '../../constants.mts'
@@ -147,8 +153,8 @@ async function run(
     markdown: boolean
     org: string
     output: string
-    reachAnalysisMemoryLimit: number
-    reachAnalysisTimeout: number
+    reachAnalysisMemoryLimit: string
+    reachAnalysisTimeout: string
     reachConcurrency: number
     reachContinueOnAnalysisErrors: boolean
     reachContinueOnInstallErrors: boolean
@@ -259,6 +265,18 @@ async function run(
       message: 'Target directory must be inside the current working directory',
       fail: 'provide a path inside the working directory',
     },
+    {
+      nook: true,
+      test: isValidReachAnalysisTimeout(reachAnalysisTimeout),
+      message: `The --reach-analysis-timeout must be ${REACH_ANALYSIS_TIMEOUT_HELP}`,
+      fail: `invalid value "${reachAnalysisTimeout}"`,
+    },
+    {
+      nook: true,
+      test: isValidReachAnalysisMemoryLimit(reachAnalysisMemoryLimit),
+      message: `The --reach-analysis-memory-limit must be ${REACH_ANALYSIS_MEMORY_LIMIT_HELP}`,
+      fail: `invalid value "${reachAnalysisMemoryLimit}"`,
+    },
   )
   if (!wasValidInput) {
     return
@@ -277,8 +295,8 @@ async function run(
     outputPath: outputPath || '',
     reachabilityOptions: {
       excludePaths,
-      reachAnalysisMemoryLimit: Number(reachAnalysisMemoryLimit),
-      reachAnalysisTimeout: Number(reachAnalysisTimeout),
+      reachAnalysisMemoryLimit,
+      reachAnalysisTimeout,
       reachConcurrency: Number(reachConcurrency),
       reachContinueOnAnalysisErrors: Boolean(reachContinueOnAnalysisErrors),
       reachContinueOnInstallErrors: Boolean(reachContinueOnInstallErrors),

src/commands/scan/cmd-scan-reach.mts

@@ -38,8 +38,8 @@ describe('socket scan reach', async () => {
 
           Reachability Options
             --exclude-paths     List of glob patterns to exclude from the scan, including SCA/SBOM manifest discovery and (when --reach is enabled) Tier 1 reachability analysis. Patterns are anchored micromatch globs matched relative to the Socket scan root, which is the command working directory (\`--cwd\` if set), not the reachability target: \`tests\` matches only \`<cwd>/tests\`; use \`**/tests\` to match at any depth. Negation patterns (\`!path\`) are not supported. Accepts a comma-separated value or multiple flags.
-            --reach-analysis-memory-limit  The maximum memory in MB to use for the reachability analysis. The default is 8192MB.
-            --reach-analysis-timeout  Set timeout for the reachability analysis. Split analysis runs may cause the total scan time to exceed this timeout significantly.
+            --reach-analysis-memory-limit  The maximum memory for the reachability analysis as a whole number optionally followed by MB or GB (e.g. 512MB, 8GB). The default is 8GB.
+            --reach-analysis-timeout  Set the timeout for the reachability analysis as a whole number optionally followed by s, m or h (e.g. 90s, 10m, 1h). Defaults to 10m. Split analysis runs may cause the total scan time to exceed this timeout significantly.
             --reach-concurrency  Set the maximum number of concurrent reachability analysis runs. It is recommended to choose a concurrency level that ensures each analysis run has at least the --reach-analysis-memory-limit amount of memory available.
             --reach-continue-on-analysis-errors  Continue reachability analysis when errors occur (timeouts, OOM, parse errors, etc.), falling back to precomputed (Tier 2) results. By default, the CLI halts on analysis errors.
             --reach-continue-on-install-errors  Continue reachability analysis when package installation fails, falling back to precomputed (Tier 2) results. By default, the CLI halts on installation errors.
@@ -1054,8 +1054,10 @@ describe('socket scan reach', async () => {
       async cmd => {
         const { code, stderr, stdout } = await spawnSocketCli(binCliPath, cmd)
         const output = stdout + stderr
-        expect(output).toContain('[DryRun]: Bailing now')
-        expect(code).toBe(0)
+        expect(output).toContain(
+          'The --reach-analysis-memory-limit must be a whole number optionally followed by MB or GB',
+        )
+        expect(code).not.toBe(0)
       },
     )
 
@@ -1065,18 +1067,20 @@ describe('socket scan reach', async () => {
         'reach',
         FLAG_DRY_RUN,
         '--reach-analysis-memory-limit',
-        '-1',
+        '512kb',
         '--org',
         'fakeOrg',
         FLAG_CONFIG,
         '{"apiToken":"fake-token"}',
       ],
-      'should show clear error for negative memory limit',
+      'should show clear error for unsupported memory unit',
       async cmd => {
         const { code, stderr, stdout } = await spawnSocketCli(binCliPath, cmd)
         const output = stdout + stderr
-        expect(output).toContain('[DryRun]: Bailing now')
-        expect(code).toBe(0)
+        expect(output).toContain(
+          'The --reach-analysis-memory-limit must be a whole number optionally followed by MB or GB',
+        )
+        expect(code).not.toBe(0)
       },
     )
 
@@ -1096,8 +1100,10 @@ describe('socket scan reach', async () => {
       async cmd => {
         const { code, stderr, stdout } = await spawnSocketCli(binCliPath, cmd)
         const output = stdout + stderr
-        expect(output).toContain('[DryRun]: Bailing now')
-        expect(code).toBe(0)
+        expect(output).toContain(
+          'The --reach-analysis-timeout must be a whole number optionally followed by s, m or h',
+        )
+        expect(code).not.toBe(0)
       },
     )
 
@@ -1107,13 +1113,13 @@ describe('socket scan reach', async () => {
         'reach',
         FLAG_DRY_RUN,
         '--reach-analysis-timeout',
-        '0',
+        '10m',
         '--org',
         'fakeOrg',
         FLAG_CONFIG,
         '{"apiToken":"fake-token"}',
       ],
-      'should show clear error for zero timeout',
+      'should accept a timeout value with a unit suffix',
       async cmd => {
         const { code, stderr, stdout } = await spawnSocketCli(binCliPath, cmd)
         const output = stdout + stderr

src/commands/scan/cmd-scan-reach.test.mts

@@ -251,8 +251,8 @@ async function scanOneRepo(
     pullRequest: 0,
     reach: {
       excludePaths: [],
-      reachAnalysisMemoryLimit: 0,
-      reachAnalysisTimeout: 0,
+      reachAnalysisMemoryLimit: '',
+      reachAnalysisTimeout: '',
       reachConcurrency: 1,
       reachContinueOnAnalysisErrors: false,
       reachContinueOnInstallErrors: false,

src/commands/scan/create-scan-from-github.mts

@@ -15,8 +15,8 @@ function makeReachOptions(
 ): ReachabilityOptions {
   return {
     excludePaths: [],
-    reachAnalysisMemoryLimit: 8192,
-    reachAnalysisTimeout: 0,
+    reachAnalysisMemoryLimit: '8192',
+    reachAnalysisTimeout: '',
     reachConcurrency: 1,
     reachContinueOnAnalysisErrors: false,
     reachContinueOnInstallErrors: false,