chore: add documentation

Author: rlmestre

CONTRIBUTING

@@ -0,0 +1,27 @@
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Linting
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+### Formatting
+
+```bash
+npm run format:check
+npm run format:write
+```

README.md

@@ -0,0 +1,88 @@
+# @herodevs/eol-shared
+
+A TypeScript utility library for End-of-Life (EOL) scanning and analysis.
+
+## Installation
+
+```bash
+npm install @herodevs/eol-shared
+```
+
+## Requirements
+
+- Node.js 22 or higher
+
+## API
+
+### [`spdxToCdxBom(spdxBom: SPDX23): CdxBom`](./src/spdx-to-cdx.mts#L61)
+
+Converts an SPDX BOM to CycloneDX format. This conversion takes the most important package and relationship data from SPDX and translates them into CycloneDX components and dependencies as closely as possible.
+
+```typescript
+import { spdxToCdxBom } from '@herodevs/eol-shared';
+import type { CdxBom } from '@herodevs/eol-shared';
+
+const spdxBom = {
+  /* your SPDX BOM data */
+};
+const cdxBom: CdxBom = spdxToCdxBom(spdxBom);
+```
+
+**Parameters**: `spdxBom` - The SPDX BOM object to convert  
+**Returns**: A CycloneDX BOM object
+
+### [`xmlStringToJSON(xmlString: string): CdxBom`](./src/cdx-xml-to-json.mts#L161)
+
+Converts a CycloneDX XML string to a JSON object. The CycloneDX spec does not change between formats, so conversion from XML to JSON is lossless.
+
+```typescript
+import { xmlStringToJSON } from '@herodevs/eol-shared';
+import type { CdxBom } from '@herodevs/eol-shared';
+
+const xmlString = `<?xml version="1.0"?>...`;
+const jsonBom: CdxBom = xmlStringToJSON(xmlString);
+```
+
+**Parameters**: `xmlString` - The XML string to parse  
+**Returns**: The parsed CycloneDX BOM object
+
+### [`trimCdxBom(cdxBom: CdxBom): CdxBom`](./src/trim-cdx-bom.mts#L3)
+
+Creates a trimmed copy of a CycloneDX BOM by removing SBOM data not necessary for EOL scanning:
+
+- `externalReferences` from components
+- `evidence` from components
+- `hashes` from components
+- `properties` from components
+
+```typescript
+import { trimCdxBom } from '@herodevs/eol-shared';
+import type { CdxBom } from '@herodevs/eol-shared';
+
+const originalBom: CdxBom = {
+  /* your CycloneDX BOM */
+};
+const trimmedBom: CdxBom = trimCdxBom(originalBom);
+```
+
+**Parameters**: `cdxBom` - The CycloneDX BOM to trim  
+**Returns**: A new trimmed CycloneDX BOM object
+
+### Types
+
+The package exports the following TypeScript types:
+
+- `CdxBom` - CycloneDX BOM structure as exported from [`@cyclonedx/cyclonedx-library`](https://github.com/CycloneDX/cyclonedx-javascript-library/blob/447db28f47ffd03b6f9c2f4a450bef0f0392c6bb/src/serialize/json/types.ts#L76)
+- `Component` - Component definition
+- `Dependency` - Dependency relationship
+- `Hash` - Hash/checksum information
+- `License` - License information
+- `ExternalReference` - External reference data
+- `ComponentScope` - Component scope enumeration
+
+## Resources
+
+This package is designed to work with:
+
+- [CycloneDX](https://cyclonedx.org/) - Industry standard for Software Bill of Materials
+- [SPDX](https://spdx.dev/) - Software Package Data Exchange standard

src/cdx-xml-to-json.mts

@@ -1,4 +1,5 @@
 import { XMLParser } from 'fast-xml-parser';
+import type { CdxBom } from './index.mts';
 
 const COLLECTION_KEYS = [
   'tools',
@@ -157,7 +158,13 @@ function transform(obj: any): any {
   return result;
 }
 
-export async function xmlStringToJSON(xml: string) {
+/**
+ * Converts a CycloneDX XML string to a JSON object.
+ * The CycloneDX spec does not change between formats, so conversion from XML to JSON is lossless.
+ * @param xml - The XML string to parse
+ * @returns The parsed CycloneDX BOM object
+ */
+export function xmlStringToJSON(xml: string): CdxBom {
   const parsed = parser.parse(xml);
   return transform(parsed);
 }

src/spdx-to-cdx.mts

@@ -59,6 +59,12 @@ function mapScope(rel: string): Scope {
   }
 }
 
+/**
+ * Converts an SPDX BOM to CycloneDX format.
+ * Takes the most important package and relationship data from SPDX and translates them into CycloneDX components and dependencies as closely as possible.
+ * @param spdx - The SPDX BOM object to convert
+ * @returns A CycloneDX BOM object
+ */
 export function spdxToCdxBom(spdx: SPDX23): CdxBom {
   const bom: CdxBom = {
     $schema: 'http://cyclonedx.org/schema/bom-1.5.schema.json',

src/trim-cdx-bom.mts

@@ -1,5 +1,11 @@
 import type { CdxBom } from './types/index.mts';
 
+/**
+ * Creates a trimmed copy of a CycloneDX BOM by removing SBOM data not necessary for EOL scanning.
+ * Removes externalReferences, evidence, hashes, and properties from components.
+ * @param cdxBom - The CycloneDX BOM to trim
+ * @returns A new trimmed CycloneDX BOM object
+ */
 export function trimCdxBom(cdxBom: CdxBom): CdxBom {
   const newBom = structuredClone(cdxBom);