verimu 0.0.19 → 0.0.20

package/dist/cli.mjs

@@ -14178,9 +14178,10 @@ var NpmScanner = class {
     if (lockfile.packages) {
       for (const [pkgPath, pkgInfo] of Object.entries(lockfile.packages)) {
         if (pkgPath === "") continue;
+        if (!pkgPath.startsWith("node_modules/")) continue;
+        if (pkgInfo.link) continue;
         const name = this.extractPackageName(pkgPath);
         if (!name || !pkgInfo.version) continue;
-        if (pkgInfo.link) continue;
         deps.push({
           name,
           version: pkgInfo.version,
@@ -15468,8 +15469,8 @@ var PnpmScanner = class {
    *   "/pkg@1.0.0(dep@2.0.0)" → name: "pkg", version: "1.0.0"
    */
   parsePackagePath(pkgPath, lockfileVersion) {
-    const path14 = pkgPath.startsWith("/") ? pkgPath.slice(1) : pkgPath;
-    const cleanPath = path14.split("_")[0].split("(")[0];
+    const path15 = pkgPath.startsWith("/") ? pkgPath.slice(1) : pkgPath;
+    const cleanPath = path15.split("_")[0].split("(")[0];
     if (!cleanPath) {
       return { name: null, version: null };
     }
@@ -15481,30 +15482,30 @@ var PnpmScanner = class {
   /**
    * Parses v6+ format: "express@4.18.2" or "@types/node@20.11.5"
    */
-  parseV6Format(path14) {
-    if (path14.startsWith("@")) {
-      const lastAtIndex = path14.lastIndexOf("@");
+  parseV6Format(path15) {
+    if (path15.startsWith("@")) {
+      const lastAtIndex = path15.lastIndexOf("@");
       if (lastAtIndex <= 0) {
         return { name: null, version: null };
       }
-      const name2 = path14.substring(0, lastAtIndex);
-      const version2 = path14.substring(lastAtIndex + 1);
+      const name2 = path15.substring(0, lastAtIndex);
+      const version2 = path15.substring(lastAtIndex + 1);
       return { name: name2, version: version2 };
     }
-    const atIndex = path14.indexOf("@");
+    const atIndex = path15.indexOf("@");
     if (atIndex < 0) {
       return { name: null, version: null };
     }
-    const name = path14.substring(0, atIndex);
-    const version = path14.substring(atIndex + 1);
+    const name = path15.substring(0, atIndex);
+    const version = path15.substring(atIndex + 1);
     return { name, version };
   }
   /**
    * Parses v5.x format: "express/4.18.2" or "@types/node/20.11.5"
    */
-  parseV5Format(path14) {
-    if (path14.startsWith("@")) {
-      const parts = path14.split("/");
+  parseV5Format(path15) {
+    if (path15.startsWith("@")) {
+      const parts = path15.split("/");
       if (parts.length < 3) {
         return { name: null, version: null };
       }
@@ -15512,12 +15513,12 @@ var PnpmScanner = class {
       const version2 = parts[2];
       return { name: name2, version: version2 };
     }
-    const slashIndex = path14.indexOf("/");
+    const slashIndex = path15.indexOf("/");
     if (slashIndex < 0) {
       return { name: null, version: null };
     }
-    const name = path14.substring(0, slashIndex);
-    const version = path14.substring(slashIndex + 1);
+    const name = path15.substring(0, slashIndex);
+    const version = path15.substring(slashIndex + 1);
     return { name, version };
   }
   /**
@@ -16825,7 +16826,8 @@ var VerimuApiClient = class {
         name: opts.name,
         ecosystem: this.mapEcosystem(opts.ecosystem),
         repository_url: opts.repositoryUrl ?? null,
-        platform: opts.platform ?? null
+        platform: opts.platform ?? null,
+        group_name: opts.groupName ?? null
       })
     });
     if (!res.ok) {
@@ -17128,34 +17130,34 @@ var JsAstAnalyzer = class {
         matchCandidates.push({ packageKey: packageKey3, line, matchKind, calledSymbol, confidence });
       };
       traverseFn(ast, {
-        ImportDeclaration: (path14) => {
-          const source = path14.node.source;
+        ImportDeclaration: (path15) => {
+          const source = path15.node.source;
           if (!(0, import_types.isStringLiteral)(source)) return;
           const pkgKey = findPackageKey(resolveImportTarget(source.value), packageMap.byName);
           if (!pkgKey) return;
-          addMatch(pkgKey, path14.node.loc?.start.line ?? 1, "import", void 0, 0.95);
-          for (const specifier of path14.node.specifiers) {
+          addMatch(pkgKey, path15.node.loc?.start.line ?? 1, "import", void 0, 0.95);
+          for (const specifier of path15.node.specifiers) {
             if ((0, import_types.isImportDefaultSpecifier)(specifier) || (0, import_types.isImportNamespaceSpecifier)(specifier) || (0, import_types.isImportSpecifier)(specifier)) {
               symbolToPackage.set(specifier.local.name, pkgKey);
             }
           }
         },
-        ExportNamedDeclaration: (path14) => {
-          const source = path14.node.source;
+        ExportNamedDeclaration: (path15) => {
+          const source = path15.node.source;
           if (!source || !(0, import_types.isStringLiteral)(source)) return;
           const pkgKey = findPackageKey(resolveImportTarget(source.value), packageMap.byName);
           if (!pkgKey) return;
-          addMatch(pkgKey, path14.node.loc?.start.line ?? 1, "export_from", void 0, 0.85);
+          addMatch(pkgKey, path15.node.loc?.start.line ?? 1, "export_from", void 0, 0.85);
         },
-        ExportAllDeclaration: (path14) => {
-          const source = path14.node.source;
+        ExportAllDeclaration: (path15) => {
+          const source = path15.node.source;
           if (!(0, import_types.isStringLiteral)(source)) return;
           const pkgKey = findPackageKey(resolveImportTarget(source.value), packageMap.byName);
           if (!pkgKey) return;
-          addMatch(pkgKey, path14.node.loc?.start.line ?? 1, "export_from", void 0, 0.85);
+          addMatch(pkgKey, path15.node.loc?.start.line ?? 1, "export_from", void 0, 0.85);
         },
-        VariableDeclarator: (path14) => {
-          const node = path14.node;
+        VariableDeclarator: (path15) => {
+          const node = path15.node;
           if (!(0, import_types.isVariableDeclarator)(node)) return;
           if (!node.init || !(0, import_types.isCallExpression)(node.init)) return;
           if (!(0, import_types.isIdentifier)(node.init.callee, { name: "require" })) return;
@@ -17168,8 +17170,8 @@ var JsAstAnalyzer = class {
             symbolToPackage.set(identifier, pkgKey);
           }
         },
-        CallExpression: (path14) => {
-          const node = path14.node;
+        CallExpression: (path15) => {
+          const node = path15.node;
           if ((0, import_types.isIdentifier)(node.callee, { name: "require" })) {
             const firstArg = node.arguments[0];
             if (firstArg && (0, import_types.isStringLiteral)(firstArg)) {
@@ -17190,12 +17192,12 @@ var JsAstAnalyzer = class {
             0.75
           );
         },
-        ImportExpression: (path14) => {
-          const source = path14.node.source;
+        ImportExpression: (path15) => {
+          const source = path15.node.source;
           if (!(0, import_types.isStringLiteral)(source)) return;
           const pkgKey = findPackageKey(resolveImportTarget(source.value), packageMap.byName);
           if (!pkgKey) return;
-          addMatch(pkgKey, path14.node.loc?.start.line ?? 1, "dynamic_import", void 0, 0.9);
+          addMatch(pkgKey, path15.node.loc?.start.line ?? 1, "dynamic_import", void 0, 0.9);
         }
       });
       for (const candidate of matchCandidates) {
@@ -18743,7 +18745,8 @@ async function uploadToVerimu(report, config) {
   const projectName = basename(config.projectPath);
   const upsertRes = await client.upsertProject({
     name: projectName,
-    ecosystem: report.project.ecosystem
+    ecosystem: report.project.ecosystem,
+    groupName: config.groupName
   });
   const projectId = upsertRes.project.id;
   const scanRes = await client.uploadSbom(projectId, buildUploadPayload(report));
@@ -18945,6 +18948,325 @@ function severityBadge2(severity) {
   return badges[severity] ?? "[???] ";
 }
 
+// src/discovery/lockfile-discovery.ts
+import { readdir as readdir3, stat } from "fs/promises";
+import { existsSync as existsSync14 } from "fs";
+import path14 from "path";
+var LOCKFILE_MAP = {
+  "pnpm-lock.yaml": { ecosystem: "npm", scanner: "pnpm" },
+  "yarn.lock": { ecosystem: "npm", scanner: "yarn" },
+  "package-lock.json": { ecosystem: "npm", scanner: "npm" },
+  "deno.lock": { ecosystem: "npm", scanner: "deno" },
+  "Cargo.lock": { ecosystem: "cargo", scanner: "cargo" },
+  "go.sum": { ecosystem: "go", scanner: "go" },
+  "Gemfile.lock": { ecosystem: "ruby", scanner: "ruby" },
+  "composer.lock": { ecosystem: "composer", scanner: "composer" },
+  "packages.lock.json": { ecosystem: "nuget", scanner: "nuget" },
+  "poetry.lock": { ecosystem: "poetry", scanner: "poetry" },
+  "uv.lock": { ecosystem: "uv", scanner: "uv" },
+  "Pipfile.lock": { ecosystem: "pip", scanner: "pip" },
+  "requirements.txt": { ecosystem: "pip", scanner: "pip" },
+  "pom.xml": { ecosystem: "maven", scanner: "maven" }
+};
+var DEFAULT_EXCLUDES = [
+  "node_modules",
+  ".git",
+  ".hg",
+  ".svn",
+  "vendor",
+  "target",
+  "dist",
+  "build",
+  ".next",
+  ".nuxt",
+  "__pycache__",
+  ".venv",
+  "venv",
+  ".tox",
+  "coverage",
+  ".cache",
+  "out",
+  ".output"
+];
+var LockfileDiscovery = class {
+  lockfileNames = Object.keys(LOCKFILE_MAP);
+  /**
+   * Discovers all lockfiles recursively starting from rootPath.
+   * Returns a list of projects that can be scanned.
+   */
+  async discover(options) {
+    const { rootPath, exclude, maxDepth } = options;
+    const absoluteRoot = path14.resolve(rootPath);
+    const discovered = [];
+    const excludePatterns = this.buildExcludePatterns(exclude);
+    await this.walkDirectory(absoluteRoot, absoluteRoot, discovered, {
+      excludePatterns,
+      maxDepth: maxDepth ?? Infinity,
+      //not set, infinite for now, can add as a cli-flag later if needed
+      currentDepth: 0
+    });
+    discovered.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return discovered;
+  }
+  /**
+   * Recursively walks directories looking for lockfiles.
+   * Stops descending into a directory once a lockfile is found
+   * (to avoid scanning nested node_modules, etc.)
+   */
+  async walkDirectory(currentPath, rootPath, results, options) {
+    const { excludePatterns, maxDepth, currentDepth } = options;
+    if (currentDepth > maxDepth) return;
+    const relativePath = path14.relative(rootPath, currentPath) || ".";
+    if (this.matchesAnyPattern(relativePath, excludePatterns)) {
+      return;
+    }
+    const foundLockfile = await this.findLockfileInDir(currentPath);
+    if (foundLockfile) {
+      results.push({
+        projectPath: currentPath,
+        relativePath,
+        lockfile: {
+          name: foundLockfile.name,
+          path: path14.join(currentPath, foundLockfile.name)
+        },
+        ecosystem: foundLockfile.ecosystem,
+        scannerType: foundLockfile.scanner
+      });
+      return;
+    }
+    let entries;
+    try {
+      entries = await readdir3(currentPath);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const entryPath = path14.join(currentPath, entry);
+      try {
+        const stats = await stat(entryPath);
+        if (stats.isDirectory()) {
+          if (this.isDefaultExclude(entry)) continue;
+          await this.walkDirectory(entryPath, rootPath, results, {
+            ...options,
+            currentDepth: currentDepth + 1
+          });
+        }
+      } catch {
+      }
+    }
+  }
+  /**
+   * Looks for a lockfile in the given directory.
+   * Returns the first match in priority order.
+   */
+  async findLockfileInDir(dirPath) {
+    const priorityOrder = [
+      "pnpm-lock.yaml",
+      "yarn.lock",
+      "package-lock.json",
+      "deno.lock",
+      "Cargo.lock",
+      "go.sum",
+      "poetry.lock",
+      "uv.lock",
+      "Pipfile.lock",
+      "composer.lock",
+      "Gemfile.lock",
+      "packages.lock.json",
+      "pom.xml",
+      "requirements.txt"
+    ];
+    for (const lockfileName of priorityOrder) {
+      const lockfilePath = path14.join(dirPath, lockfileName);
+      if (existsSync14(lockfilePath)) {
+        const info = LOCKFILE_MAP[lockfileName];
+        return { name: lockfileName, ...info };
+      }
+    }
+    return null;
+  }
+  /**
+   * Builds exclude patterns from user input + defaults.
+   */
+  buildExcludePatterns(userExcludes) {
+    const patterns = [];
+    for (const dir of DEFAULT_EXCLUDES) {
+      patterns.push(`**/${dir}`);
+      patterns.push(`**/${dir}/**`);
+    }
+    if (userExcludes) {
+      patterns.push(...userExcludes);
+    }
+    return patterns;
+  }
+  /**
+   * Quick check if a directory name is in the default exclude list.
+   */
+  isDefaultExclude(dirName) {
+    return DEFAULT_EXCLUDES.includes(dirName);
+  }
+  /**
+   * Checks if a path matches any of the given glob patterns.
+   * Uses simple glob matching (supports *, **, ?).
+   */
+  matchesAnyPattern(relativePath, patterns) {
+    const normalized = relativePath.replace(/\\/g, "/");
+    for (const pattern of patterns) {
+      if (this.matchGlob(normalized, pattern)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Simple glob matcher supporting:
+   * - * (matches any characters except /)
+   * - ** (matches any characters including /)
+   * - ? (matches single character)
+   */
+  matchGlob(str, pattern) {
+    let regex = pattern.replace(/\\/g, "/").replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/{{GLOBSTAR}}/g, ".*").replace(/\?/g, ".");
+    regex = `^${regex}$`;
+    return new RegExp(regex).test(str);
+  }
+};
+
+// src/discovery/orchestrator.ts
+import { basename as basename2 } from "path";
+var MultiProjectOrchestrator = class {
+  discovery = new LockfileDiscovery();
+  reporter = new ConsoleReporter();
+  /**
+   * Gets a display name for a project (uses directory name instead of "." for root)
+   */
+  getDisplayName(project, rootPath) {
+    if (project.relativePath === ".") {
+      return basename2(rootPath);
+    }
+    return project.relativePath;
+  }
+  /**
+   * Discovers and scans all projects in a directory tree.
+   */
+  async scanAll(config) {
+    const startTime = Date.now();
+    const apiKey = config.apiKey;
+    const apiBaseUrl = config.apiBaseUrl;
+    console.log(`
+Discovering projects in ${config.projectPath}...`);
+    const projects = await this.discovery.discover({
+      rootPath: config.projectPath,
+      exclude: config.exclude
+    });
+    if (projects.length === 0) {
+      console.log("No projects with lockfiles found.");
+      return {
+        totalDiscovered: 0,
+        successful: [],
+        failed: [],
+        skipped: [],
+        durationMs: Date.now() - startTime
+      };
+    }
+    const isSingleProject = projects.length === 1;
+    const groupName = isSingleProject ? config.groupName : config.groupName || basename2(config.projectPath);
+    console.log(`Found ${projects.length} project(s):
+`);
+    for (const p of projects) {
+      const displayName = this.getDisplayName(p, config.projectPath);
+      console.log(`  \u2022 ${displayName} (${p.scannerType})`);
+    }
+    if (!isSingleProject) {
+      if (!config.groupName) {
+        console.log(`
+  \u2139 Auto-grouping projects as: "${groupName}"`);
+        console.log("  (Use --group to specify a custom group name)\n");
+      } else {
+        console.log(`
+  \u2139 Grouping projects as: "${groupName}"
+`);
+      }
+    } else {
+      console.log("");
+    }
+    const successful = [];
+    const failed = [];
+    for (let i = 0; i < projects.length; i++) {
+      const project = projects[i];
+      const displayName = this.getDisplayName(project, config.projectPath);
+      console.log("\u2500".repeat(60));
+      console.log(`[${i + 1}/${projects.length}] Scanning: ${displayName}`);
+      console.log("\u2500".repeat(60));
+      console.log("");
+      try {
+        const sbomOutput = this.deriveSbomPath(project, config.sbomOutput);
+        const report = await scan({
+          ...config,
+          projectPath: project.projectPath,
+          sbomOutput,
+          groupName,
+          // Use auto-derived or user-provided group name
+          apiKey: void 0
+          // Don't upload in scan, do it separately
+        });
+        console.log(this.reporter.report(report));
+        if (apiKey) {
+          console.log("");
+          console.log(`  Syncing ${displayName} to Verimu platform...`);
+          try {
+            const uploadConfig = {
+              ...config,
+              projectPath: project.projectPath,
+              groupName,
+              // Use auto-derived or user-provided group name
+              apiKey,
+              apiBaseUrl
+            };
+            const uploadResult = await uploadToVerimu(report, uploadConfig);
+            if (uploadResult.projectCreated) {
+              console.log(`  \u2713 Project created: ${displayName}`);
+            }
+            console.log(`  \u2713 ${uploadResult.totalDependencies} dependencies tracked`);
+            console.log(renderPlatformScan(displayName, uploadResult));
+            console.log(`  \u2713 Dashboard: ${uploadResult.dashboardUrl}`);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.log(`  \u26A0 Platform sync failed: ${msg}`);
+            console.log("  Your SBOM was still generated locally. You can upload it manually.");
+          }
+        }
+        console.log("");
+        successful.push({ project, report });
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.log(`  \u2717 Failed: ${errorMsg}`);
+        console.log("");
+        failed.push({ project, error: errorMsg });
+        throw error;
+      }
+    }
+    return {
+      totalDiscovered: projects.length,
+      successful,
+      failed,
+      skipped: [],
+      durationMs: Date.now() - startTime
+    };
+  }
+  /**
+   * Derives SBOM output path for a project.
+   * Places SBOMs in project directories by default.
+   */
+  deriveSbomPath(project, configOutput) {
+    if (configOutput) {
+      const base = configOutput.replace(/\.cdx\.json$/, "");
+      const sanitized = project.relativePath.replace(/[/\\]/g, "-");
+      return `${base}.${sanitized}.cdx.json`;
+    }
+    return `${project.projectPath}/sbom.cdx.json`;
+  }
+};
+
 // src/cli.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
@@ -18977,7 +19299,11 @@ function parseArgs(argv) {
     skipCveCheck: false,
     skipUpload: false,
     cyclonedxVersion: "1.7",
-    contextLines: void 0
+    contextLines: void 0,
+    groupName: void 0,
+    recursive: true,
+    // Recursive by default
+    exclude: void 0
   };
   let i = 0;
   while (i < args.length) {
@@ -19023,6 +19349,20 @@ function parseArgs(argv) {
         throw new Error(`Invalid CycloneDX version: ${val}`);
       }
       result.cyclonedxVersion = val;
+    } else if (arg === "--group-name" || arg.startsWith("--group-name=")) {
+      const val = arg.startsWith("--group-name=") ? arg.split("=")[1] : args[++i];
+      if (!val || val.startsWith("--")) {
+        throw new Error("--group-name requires a value");
+      }
+      result.groupName = val;
+    } else if (arg === "--no-recursive" || arg === "--not-recursive") {
+      result.recursive = false;
+    } else if (arg === "--exclude") {
+      const val = args[++i];
+      if (!val || val.startsWith("--")) {
+        throw new Error("--exclude requires a comma-separated list of patterns");
+      }
+      result.exclude = val.split(",").map((p) => p.trim());
     }
     i++;
   }
@@ -19065,8 +19405,32 @@ async function main() {
     // Don't pass apiKey to scan() if --skip-upload — we'll handle upload separately for better logging
     apiKey: apiKey && !args.skipUpload ? void 0 : void 0,
     apiBaseUrl,
-    numContextLines: args.contextLines
+    numContextLines: args.contextLines,
+    groupName: args.groupName
   };
+  if (args.recursive) {
+    const orchestrator = new MultiProjectOrchestrator();
+    let result;
+    try {
+      result = await orchestrator.scanAll({
+        ...config,
+        recursive: true,
+        exclude: args.exclude,
+        // Pass API key for platform uploads
+        apiKey: apiKey && !args.skipUpload ? apiKey : void 0,
+        apiBaseUrl
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError(msg);
+      process.exit(2);
+    }
+    printMultiProjectSummary(result);
+    if (result.failed.length > 0) {
+      process.exit(1);
+    }
+    return;
+  }
   let report;
   try {
     report = await scan(config);
@@ -19107,12 +19471,50 @@ async function main() {
     process.exit(1);
   }
 }
+function printMultiProjectSummary(result) {
+  console.log("\n" + "\u2500".repeat(60));
+  console.log("Multi-Project Scan Summary");
+  console.log("\u2500".repeat(60));
+  console.log(`
+Projects discovered: ${result.totalDiscovered}`);
+  console.log(`  \u2713 Successful: ${result.successful.length}`);
+  console.log(`  \u2717 Failed: ${result.failed.length}`);
+  if (result.successful.length > 0) {
+    const totalDeps = result.successful.reduce(
+      (sum, r) => sum + r.report.summary.totalDependencies,
+      0
+    );
+    const totalVulns = result.successful.reduce(
+      (sum, r) => sum + r.report.summary.totalVulnerabilities,
+      0
+    );
+    console.log(`
+Total dependencies: ${totalDeps}`);
+    console.log(`Total vulnerabilities: ${totalVulns}`);
+    const critical = result.successful.reduce((sum, r) => sum + r.report.summary.critical, 0);
+    const high = result.successful.reduce((sum, r) => sum + r.report.summary.high, 0);
+    const medium = result.successful.reduce((sum, r) => sum + r.report.summary.medium, 0);
+    const low = result.successful.reduce((sum, r) => sum + r.report.summary.low, 0);
+    if (totalVulns > 0) {
+      console.log(`  Critical: ${critical}, High: ${high}, Medium: ${medium}, Low: ${low}`);
+    }
+  }
+  if (result.failed.length > 0) {
+    console.log("\nFailed projects:");
+    for (const f of result.failed) {
+      console.log(`  \u2022 ${f.project.relativePath}: ${f.error}`);
+    }
+  }
+  console.log(`
+Completed in ${(result.durationMs / 1e3).toFixed(2)}s`);
+  console.log("");
+}
 function printHelp() {
   console.log(`
   Verimu \u2014 CRA Compliance Scanner
 
   Usage:
-    verimu                          Scan current directory
+    verimu                          Scan current directory (recursively)
     verimu scan [options]           Full scan (SBOM + CVE check)
     verimu generate-sbom [options]  Generate SBOM only (no CVE check)
     verimu help                     Show this help
@@ -19121,23 +19523,35 @@ function printHelp() {
   Options:
     --path, -p <dir>       Project directory to scan (default: .)
     --output, -o <file>    CycloneDX output path (SPDX/SWID are written alongside it)
+    --group-name <name>    Group name for organizing related projects in dashboard
     --fail-on <severity>   Exit 1 if vulns at or above: CRITICAL, HIGH, MEDIUM, LOW
     --skip-cve             Skip CVE vulnerability checking
     --skip-upload          Don't sync to Verimu platform (even if API key is set)
     --context-lines <n>    Snippet context lines around matches (default: 4, clamped to 0..20)
     --cdx-version <ver>    CycloneDX spec: 1.4, 1.5, 1.6, 1.7 (default: 1.7)
 
+  Project Discovery:
+    --no-recursive         Disable recursive discovery (scan only root directory)
+    --exclude <patterns>   Exclude paths matching patterns (comma-separated globs)
+
+  Note: Verimu automatically discovers all projects recursively by default.
+  For monorepos with multiple lockfiles, projects are auto-grouped by directory name.
+  Single lockfile projects are treated normally without grouping.
+
   Environment:
     VERIMU_API_KEY         API key for Verimu platform (from app.verimu.com)
     VERIMU_API_URL         Custom API URL (default: https://api.verimu.com)
 
   Examples:
-    npx verimu                                    # Quick scan
+    npx verimu                                    # Scan all projects recursively
     VERIMU_API_KEY=vmu_xxx npx verimu             # Scan + sync to platform
     npx verimu scan --fail-on HIGH                # Fail CI on HIGH+ vulns
+    npx verimu scan --group-name my-app           # Group projects with custom name
     npx verimu scan --context-lines 8             # Wider context around usage snippets
     npx verimu scan --cdx-version 1.5             # Specify CycloneDX version
     npx verimu scan --path ./backend --output ./reports/sbom.json
+    npx verimu scan --no-recursive                # Scan only root directory
+    npx verimu scan --exclude "legacy/*"          # Exclude legacy projects
 
   Supported ecosystems:
     npm (package-lock.json)         pip (requirements.txt)