refactor(reachability): use full names instead of "tier 1/2/3" + bump Coana CLI to 15.5.7 (#1376)

* refactor(reachability): use descriptive names instead of tier 1/2/3

Refer to the reachability analysis types by descriptive names in all
user-facing text (command/flag help, output, error messages, log
messages, comments, and docs):

- Full application reachability (formerly Tier 1)
- Precomputed reachability (formerly Tier 2)
- Dependency reachability (formerly Tier 3)

Backend wire contracts are unchanged: the scan_type value, the
tier1-reachability-scan/finalize endpoint, request/response field
names, and code identifiers retain their existing names. Only
human-readable text is updated.

A new Reachability analysis section in the README documents the names
and notes the previous Tier 1/2/3 naming for users migrating.

* refactor(reachability): apply descriptive names to merged changes and update tests

Rename the 'tier 1' wording introduced by the --reach-retain-facts-file
flag (merged from v1.x) to 'full application reachability', and update
the reachability test snapshots and assertions to match the descriptive
naming.

* chore(deps): bump @coana-tech/cli to 15.5.7 (1.1.126)

Pin @coana-tech/cli to the latest published 15.5.7 and bump the CLI
patch version with a matching changelog entry.

* docs: drop redundant tier-naming note from README

The 'formerly Tier 1/2/3' mapping is already inline on each reachability
type, so the trailing note is redundant.

Author: mtorp

CHANGELOG.md

@@ -4,6 +4,12 @@ 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.126](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.126) - 2026-06-22
+
+### Changed
+- Reachability analysis types are now referred to by descriptive names in command help, output, and docs: Full application reachability (formerly Tier 1), Precomputed reachability (formerly Tier 2), and Dependency reachability (formerly Tier 3).
+- Updated the Coana CLI to v `15.5.7`.
+
 ## [1.1.125](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.125) - 2026-06-22
 
 ### Added
@@ -14,7 +20,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [1.1.124](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.124) - 2026-06-19
 
-- `socket scan create --reach` accepts a new `--reach-retain-facts-file` flag. By default the CLI deletes the `.socket.facts.json` reachability report from the scan directory after a successful scan; pass this flag to keep it (e.g. for inspection or debugging). **Important:** you must delete the retained `.socket.facts.json` before running a fresh tier 1 reachability scan — a stale file left in place is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan results will not be reliable.
+- `socket scan create --reach` accepts a new `--reach-retain-facts-file` flag. By default the CLI deletes the `.socket.facts.json` reachability report from the scan directory after a successful scan; pass this flag to keep it (e.g. for inspection or debugging). **Important:** you must delete the retained `.socket.facts.json` before running a fresh full application reachability scan — a stale file left in place is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan results will not be reliable.
 
 ### Changed
 - Updated the Coana CLI to v `15.5.4`.

README.md

@@ -60,6 +60,14 @@ All aliases support the flags and arguments of the commands they alias.
 
 - `socket ci` - Alias for `socket scan create --report` (creates report and exits with error if unhealthy)
 
+## Reachability analysis
+
+Socket reachability analysis comes in three forms:
+
+- **Full application reachability** (formerly Tier 1): Analyzes your application together with its dependencies to determine whether vulnerable code is actually invoked from your code through the full dependency graph — the highest-precision reachability analysis. Run it with `socket scan create --reach`.
+- **Precomputed reachability** (formerly Tier 2): Determines whether vulnerable code in transitive dependencies is reachable through your direct dependencies, using precomputed static analysis of dependency chains (no access to your application code required). In the CLI this is the fallback used when full application reachability cannot complete (see the `--reach-continue-on-*` flags).
+- **Dependency reachability** (formerly Tier 3): Package-level filtering that detects which dependencies are actually used, so CVEs in unused/dead dependencies can be filtered out.
+
 ## Flags
 
 ### Output flags

package.json

@@ -1,6 +1,6 @@
 {
   "name": "socket",
-  "version": "1.1.125",
+  "version": "1.1.126",
   "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.5.5",
+    "@coana-tech/cli": "15.5.7",
     "@cyclonedx/cdxgen": "12.1.2",
     "@dotenvx/dotenvx": "1.49.0",
     "@eslint/compat": "1.3.2",

pnpm-lock.yaml

@@ -116,7 +116,7 @@ const generalFlags: MeowFlags = {
   reach: {
     type: 'boolean',
     default: false,
-    description: 'Run tier 1 full application reachability analysis',
+    description: 'Run full application reachability analysis',
   },
   readOnly: {
     type: 'boolean',

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

@@ -40,13 +40,13 @@ describe('socket scan create', async () => {
             --committers        Committers
             --cwd               working directory, defaults to process.cwd()
             --default-branch    Set the default branch of the repository to the branch of this full-scan. Should only need to be done once, for example for the "main" or "master" branch.
-            --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.
+            --exclude-paths     List of glob patterns to exclude from the scan, including SCA/SBOM manifest discovery and (when --reach is enabled) full application 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.
             --interactive       Allow for interactive elements, asking for input. Use --no-interactive to prevent any input questions, defaulting them to cancel/no.
             --json              Output as JSON
             --markdown          Output as Markdown
             --org               Force override the organization slug, overrides the default org from config
             --pull-request      Pull request number
-            --reach             Run tier 1 full application reachability analysis
+            --reach             Run full application reachability analysis
             --read-only         Similar to --dry-run except it can read from remote, stops before it would create an actual report
             --repo              Repository name
             --report            Wait for the scan creation to complete, then basically run \`socket scan report\` on it
@@ -59,8 +59,8 @@ describe('socket scan create', async () => {
             --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.
+            --reach-continue-on-analysis-errors  Continue reachability analysis when errors occur (timeouts, OOM, parse errors, etc.), falling back to precomputed reachability 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 reachability results. By default, the CLI halts on installation errors.
             --reach-continue-on-missing-lock-files  Continue reachability analysis when a Gradle or SBT project is missing its lock file (or version catalog / pre-generated SBOM). By default, the CLI halts.
             --reach-continue-on-no-source-files  Continue reachability analysis when a workspace contains no source files for its ecosystem. By default, the CLI halts.
             --reach-debug       Enable debug mode for reachability analysis. Provides verbose logging from the reachability CLI.
@@ -69,7 +69,7 @@ describe('socket scan create', async () => {
             --reach-disable-external-tool-checks  Disable external tool checks during reachability analysis.
             --reach-ecosystems  List of ecosystems to conduct reachability analysis on, as either a comma separated value or as multiple flags. Defaults to all ecosystems.
             --reach-enable-analysis-splitting  Allow the reachability analysis to partition CVEs into buckets that are processed in separate analysis runs. May improve accuracy, but not recommended by default.
-            --reach-retain-facts-file  Keep the \`.socket.facts.json\` reachability report that the analysis writes to the scan directory instead of deleting it after a successful scan. IMPORTANT: you must delete this file before running a fresh tier 1 reachability scan. A stale \`.socket.facts.json\` left in place is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan results will not be reliable.
+            --reach-retain-facts-file  Keep the \`.socket.facts.json\` reachability report that the analysis writes to the scan directory instead of deleting it after a successful scan. IMPORTANT: you must delete this file before running a fresh full application reachability scan. A stale \`.socket.facts.json\` left in place is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan results will not be reliable.
             --reach-skip-cache  Skip caching-based optimizations. By default, the reachability analysis will use cached configurations from previous runs to speed up the analysis.
             --reach-use-only-pregenerated-sboms  When using this option, the scan is created based only on pre-generated CDX and SPDX files in your project.
             --reach-version     Override the version of @coana-tech/cli used for reachability analysis. Default: <coana-version>.

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

@@ -31,7 +31,7 @@ import type {
 
 export const CMD_NAME = 'reach'
 
-const description = 'Compute tier 1 reachability'
+const description = 'Compute full application reachability'
 
 const hidden = true
 

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

@@ -20,7 +20,7 @@ describe('socket scan reach', async () => {
     async cmd => {
       const { code, stderr, stdout } = await spawnSocketCli(binCliPath, cmd)
       expect(stdout).toMatchInlineSnapshot(`
-        "Compute tier 1 reachability
+        "Compute full application reachability
 
           Usage
             $ socket scan reach [options] [CWD=.]
@@ -37,12 +37,12 @@ describe('socket scan reach', async () => {
             --output            Path to write the reachability report to (must end with .json). Defaults to .socket.facts.json in the current working directory.
 
           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.
+            --exclude-paths     List of glob patterns to exclude from the scan, including SCA/SBOM manifest discovery and (when --reach is enabled) full application 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 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.
+            --reach-continue-on-analysis-errors  Continue reachability analysis when errors occur (timeouts, OOM, parse errors, etc.), falling back to precomputed reachability 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 reachability results. By default, the CLI halts on installation errors.
             --reach-continue-on-missing-lock-files  Continue reachability analysis when a Gradle or SBT project is missing its lock file (or version catalog / pre-generated SBOM). By default, the CLI halts.
             --reach-continue-on-no-source-files  Continue reachability analysis when a workspace contains no source files for its ecosystem. By default, the CLI halts.
             --reach-debug       Enable debug mode for reachability analysis. Provides verbose logging from the reachability CLI.
@@ -51,7 +51,7 @@ describe('socket scan reach', async () => {
             --reach-disable-external-tool-checks  Disable external tool checks during reachability analysis.
             --reach-ecosystems  List of ecosystems to conduct reachability analysis on, as either a comma separated value or as multiple flags. Defaults to all ecosystems.
             --reach-enable-analysis-splitting  Allow the reachability analysis to partition CVEs into buckets that are processed in separate analysis runs. May improve accuracy, but not recommended by default.
-            --reach-retain-facts-file  Keep the \`.socket.facts.json\` reachability report that the analysis writes to the scan directory instead of deleting it after a successful scan. IMPORTANT: you must delete this file before running a fresh tier 1 reachability scan. A stale \`.socket.facts.json\` left in place is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan results will not be reliable.
+            --reach-retain-facts-file  Keep the \`.socket.facts.json\` reachability report that the analysis writes to the scan directory instead of deleting it after a successful scan. IMPORTANT: you must delete this file before running a fresh full application reachability scan. A stale \`.socket.facts.json\` left in place is picked up as a pre-generated input and silently overrides fresh analysis, so the new scan results will not be reliable.
             --reach-skip-cache  Skip caching-based optimizations. By default, the reachability analysis will use cached configurations from previous runs to speed up the analysis.
             --reach-use-only-pregenerated-sboms  When using this option, the scan is created based only on pre-generated CDX and SPDX files in your project.
             --reach-version     Override the version of @coana-tech/cli used for reachability analysis. Default: <coana-version>.
@@ -1143,7 +1143,7 @@ describe('socket scan reach', async () => {
         expect(output.length).toBeGreaterThan(0)
       },
       // Non-dry-run invocation actually starts Coana, which under v15
-      // performs more upfront work (tier1 scan registration, legacy-mode
+      // performs more upfront work (full application reachability scan registration, legacy-mode
       // resolution) before failing on the bad memory limit. The default
       // 30s cmdit timeout is too tight for that path on slower CI runners.
       { timeout: 60_000 },
@@ -1185,7 +1185,7 @@ describe('socket scan reach', async () => {
       'should prioritize help over other flags',
       async cmd => {
         const { code, stdout } = await spawnSocketCli(binCliPath, cmd)
-        expect(stdout).toContain('Compute tier 1 reachability')
+        expect(stdout).toContain('Compute full application reachability')
         expect(code).toBe(0)
       },
     )

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

@@ -8,11 +8,13 @@ export type FinalizeTier1ScanOptions = {
 }
 
 /**
- * Finalize a tier1 reachability scan.
- *  - Associates the tier1 reachability scan metadata with the full scan
+ * Finalize a full application reachability scan (formerly known as "tier 1";
+ * the wire endpoint and request fields below retain the legacy tier1 name as
+ * a backend contract).
+ *  - Associates the reachability scan metadata with the full scan
  *    (or with `null` when called from a standalone reachability flow that
  *    has no full scan to bind to).
- *  - Transitions the tier1 reachability scan to its DONE terminal state.
+ *  - Transitions the reachability scan to its DONE terminal state.
  */
 export async function finalizeTier1Scan(
   tier1ReachabilityScanId: string,