docs: fix broken programmatic usage example in README

[dmchaledev]

Problem

The Programmatic usage example in the README documents an API that does not exist and will not run if copy-pasted. As the primary programmatic example on a published npm package, this is a high-friction first impression for adopters.

The current example:

import { diff } from '@hailbytes/sbom-diff';

const report = await diff('old.cdx.json', 'new.cdx.json');
// ...
console.log(report.upgraded); // { from: Component, to: Component }[]

Three things are wrong:

1. diff does not take file paths. The real signature is diff(a: SBOM, b: SBOM): ChangeReport — it takes two parsed SBOM objects. Passing path strings makes TypeScript error and crashes at runtime (it tries to read .components off a string).
2. diff is not async. await diff(...) is misleading — it returns a ChangeReport synchronously.
3. report.upgraded is mis-typed in the comment. It is VersionChange[] ({ component, from, to, isMajorBump }), where from/to are version strings, not Components.

Fix

Rewrite the example to use the real exported API — parse + diff + renderReport — mirroring the JSDoc example already in src/index.ts. Also document the actual report fields, including fixedCVEs, and show rendering output.

import { readFile } from 'node:fs/promises';
import { parse, diff, renderReport } from '@hailbytes/sbom-diff';

const oldSBOM = parse(await readFile('old.cdx.json', 'utf-8'));
const newSBOM = parse(await readFile('new.cdx.json', 'utf-8'));

const report = diff(oldSBOM, newSBOM);
console.log(renderReport(report, 'markdown'));

Docs-only change — no source or test changes. Tests (20) and build remain green.

https://claude.ai/code/session_019aMbKwZ3ZJMRJPgTfVFUNi

---

Generated by Claude Code