From d6b903ef504e1ee22968b800710de9513a4320b9 Mon Sep 17 00:00:00 2001
From: mayank-dev-15 <mayank-dev-15@users.noreply.github.com>
Date: Tue, 23 Jun 2026 19:39:23 +0530
Subject: [PATCH] fix: add actionable guidance to flag incompatibility errors
 (fixes #401)

Error messages now explain what each flag does and suggest which one to use:

- --offline/--offline-db vs --osv-url: choose offline or online mode
- --no-cache vs --offline: cache only applies to online scans
- --fix vs --json: interactive fixes or JSON output, not both
- --create-pr vs --json: PR or JSON output, not both
- --report vs --json: HTML report or JSON output, pick one
---
 src/cli/validate.ts | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/src/cli/validate.ts b/src/cli/validate.ts
index fff3da9f..acb01eca 100644
--- a/src/cli/validate.ts
+++ b/src/cli/validate.ts
@@ -3,11 +3,17 @@ import type { ParsedOptions } from "../types.js";
 
 export function validateOptions(options: ParsedOptions): void {
   if ((options.offline || options.offlineDb) && options.osvUrl) {
-    throw new Error("--offline/--offline-db cannot be used with --osv-url");
+    throw new Error(
+      "--offline/--offline-db cannot be used with --osv-url. " +
+      "Choose offline mode (local DB) or online mode (custom OSV endpoint), not both."
+    );
   }
 
   if (options.noCache && (options.offline || options.offlineDb)) {
-    throw new Error("--no-cache cannot be used with --offline or --offline-db");
+    throw new Error(
+      "--no-cache cannot be used with --offline or --offline-db. " +
+      "In offline mode the local advisory DB is used directly; --no-cache only applies to online scans."
+    );
   }
 
   if (options.osvUrl) {
@@ -19,7 +25,10 @@ export function validateOptions(options: ParsedOptions): void {
   }
 
   if (options.fix && options.json) {
-    throw new Error("--fix cannot be used with --json");
+    throw new Error(
+      "--fix cannot be used with --json. " +
+      "Use --fix to apply fixes interactively, or --json to output scan results as JSON — not both at once."
+    );
   }
 
   if (options.createPr && !options.fix) {
@@ -27,7 +36,10 @@ export function validateOptions(options: ParsedOptions): void {
   }
 
   if (options.createPr && options.json) {
-    throw new Error("--create-pr cannot be used with --json");
+    throw new Error(
+      "--create-pr cannot be used with --json. " +
+      "Use --create-pr to open a pull request with fixes, or --json to output results — not both."
+    );
   }
 
   if (options.prBase && !options.createPr) {
@@ -35,7 +47,10 @@ export function validateOptions(options: ParsedOptions): void {
   }
 
   if (options.report && options.json) {
-    throw new Error("--report cannot be used with --json");
+    throw new Error(
+      "--report cannot be used with --json. " +
+      "Use --report to generate an HTML report, or --json for machine-readable output — pick one."
+    );
   }
 
   if (options.caCert) {