fix(cli): default --format to text instead of crashing on the documented usage

[dmchaledev]

Summary

The package's primary, documented invocation crashes. Running the README's quick-start command:

npx @hailbytes/sbom-diff old.json new.json

exits with:

Error: Unsupported format: old.json
    at renderReport (.../reporter.js:11:24)

Root cause

In src/cli.ts the --format value was resolved with:

const formatArg = args.find(a => a.startsWith('--format='))?.split('=')[1]
  ?? args[args.indexOf('--format') + 1];
const format = (formatArg as ReportFormat) ?? 'text';

When --format is absent, args.indexOf('--format') returns -1, so args[-1 + 1] resolves to args[0] — the first positional argument (the old SBOM path). That value is not undefined, so the ?? 'text' default never applies, and the path string gets passed to renderReport, which throws on the unknown format.

Net effect: the only way to not crash was to always pass --format explicitly, contradicting the README.

Fix

• Extracted argument parsing into a small, pure, unit-tested parseArgs (src/args.ts) that:
  • defaults the format to text when --format is omitted,
  • supports both --format json (spaced) and --format=json (inline),
  • validates the format value and surfaces a clear one-line error (Invalid format: "xml". Valid formats: text, json, markdown.) instead of a stack trace.
• cli.ts now consumes parseArgs and prints usage/validation errors to stderr with exit code 1.
• Added src/__tests__/args.test.ts covering the default, both flag forms, the missing-args case, and the invalid-format case.

Verification

$ node dist/cli.js old.json new.json            # previously crashed
SBOM Diff Report
=================
...
exit: 0

$ node dist/cli.js old.json new.json --format xml
Invalid format: "xml". Valid formats: text, json, markdown.
exit: 1

npm run typecheck, npm run lint, and npm test (25 tests) all pass.

Noted follow-up (out of scope for this PR)

While testing I found a separate correctness issue: diff() keys components by purl ?? name, but purls embed the version (pkg:npm/lodash@4.17.20). So a version bump produces two distinct keys and is reported as removed + added rather than upgraded — silently disabling the headline "upgraded dependencies" feature for any SBOM that includes versioned purls. Happy to file a separate issue / PR to normalize purls (strip the version qualifier) for matching.

https://claude.ai/code/session_01YMe4qfgnC6BuCvLreBNnkQ

---

Generated by Claude Code