@euconform/core 1.4.0 → 1.5.0

package/dist/sbom/purl.js

@@ -0,0 +1,56 @@
+/**
+ * Parse a Package URL (purl) string into its components.
+ * Follows the purl spec: pkg:type/namespace/name@version?qualifiers#subpath
+ * Returns null for invalid or non-pkg URLs.
+ */
+export function parsePurl(purl) {
+    if (!purl || !purl.startsWith("pkg:"))
+        return null;
+    // Strip qualifiers and subpath
+    let rest = purl.slice(4); // remove "pkg:"
+    const hashIdx = rest.indexOf("#");
+    if (hashIdx !== -1)
+        rest = rest.slice(0, hashIdx);
+    const queryIdx = rest.indexOf("?");
+    if (queryIdx !== -1)
+        rest = rest.slice(0, queryIdx);
+    // Split type from the rest: type/...
+    const slashIdx = rest.indexOf("/");
+    if (slashIdx <= 0)
+        return null;
+    const type = rest.slice(0, slashIdx);
+    let remainder = rest.slice(slashIdx + 1);
+    try {
+        remainder = decodeURIComponent(remainder);
+    }
+    catch {
+        return null;
+    }
+    // Extract version
+    let version;
+    const atIdx = remainder.lastIndexOf("@");
+    if (atIdx !== -1) {
+        version = remainder.slice(atIdx + 1);
+        remainder = remainder.slice(0, atIdx);
+    }
+    // Split namespace/name (last segment is name, rest is namespace)
+    const lastSlash = remainder.lastIndexOf("/");
+    let namespace;
+    let name;
+    if (lastSlash !== -1) {
+        namespace = remainder.slice(0, lastSlash);
+        name = remainder.slice(lastSlash + 1);
+    }
+    else {
+        name = remainder;
+    }
+    if (!name)
+        return null;
+    return {
+        scheme: "pkg",
+        type,
+        namespace: namespace || undefined,
+        name,
+        version: version || undefined,
+    };
+}

package/dist/sbom/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Minimal CycloneDX types covering fields relevant to AI component detection.
+ * Supports CycloneDX JSON format versions 1.4, 1.5, 1.6.
+ */
+export interface CycloneDxBom {
+    bomFormat: "CycloneDX";
+    specVersion: string;
+    version?: number;
+    metadata?: CycloneDxMetadata;
+    components?: CycloneDxComponent[];
+}
+export interface CycloneDxMetadata {
+    timestamp?: string;
+    tools?: Array<{
+        name?: string;
+        version?: string;
+    }>;
+    component?: CycloneDxComponent;
+}
+export interface CycloneDxComponent {
+    type: string;
+    name: string;
+    version?: string;
+    purl?: string;
+    group?: string;
+    description?: string;
+    scope?: "required" | "optional" | "excluded";
+    properties?: Array<{
+        name: string;
+        value: string;
+    }>;
+    /** CycloneDX ML-BOM extensions (1.5+) */
+    modelCard?: unknown;
+    data?: Array<{
+        type?: string;
+    }>;
+}
+export declare const SUPPORTED_SPEC_VERSIONS: readonly ["1.4", "1.5", "1.6"];
+//# sourceMappingURL=types.d.ts.map

package/dist/sbom/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sbom/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,WAAW,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;IAC7C,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,yCAAyC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjC;AAED,eAAO,MAAM,uBAAuB,gCAAiC,CAAC"}

package/dist/sbom/types.js

@@ -0,0 +1,5 @@
+/**
+ * Minimal CycloneDX types covering fields relevant to AI component detection.
+ * Supports CycloneDX JSON format versions 1.4, 1.5, 1.6.
+ */
+export const SUPPORTED_SPEC_VERSIONS = ["1.4", "1.5", "1.6"];

package/dist/validation/index.d.ts

@@ -0,0 +1,2 @@
+export { validate, type ValidationResult, type ValidationError, type SchemaType, type ValidateOptions, } from "./schema-validator";
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/validation/index.js

@@ -0,0 +1 @@
+export { validate, } from "./schema-validator";

package/dist/validation/schema-validator.d.ts

@@ -0,0 +1,18 @@
+export interface ValidationError {
+    path: string;
+    message: string;
+    keyword: string;
+    expected?: unknown;
+    received?: unknown;
+}
+export type SchemaType = "report.v1" | "aibom.v1" | "aibom.v1.1" | "ci.v1" | "bundle.v1";
+export interface ValidationResult {
+    valid: boolean;
+    schemaType: SchemaType;
+    errors: ValidationError[];
+}
+export interface ValidateOptions {
+    strict?: boolean;
+}
+export declare function validate(data: unknown, _options?: ValidateOptions): ValidationResult;
+//# sourceMappingURL=schema-validator.d.ts.map

package/dist/validation/schema-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validator.d.ts","sourceRoot":"","sources":["../../src/validation/schema-validator.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,WAAW,CAAC;AAEzF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAmCD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAyEpF"}

package/dist/validation/schema-validator.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import addFormats from "ajv-formats";
+import Ajv2020 from "ajv/dist/2020";
+// Resolve schema directory relative to this file at runtime.
+// When bundled into packages/cli/dist, schemas are copied to dist/schemas/.
+// When running from source at packages/core/src/validation/, schemas are at ../../../../docs/spec/schemas.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const _bundledSchemasDir = resolve(__dirname, "schemas");
+const schemasDir = existsSync(_bundledSchemasDir)
+    ? _bundledSchemasDir
+    : resolve(__dirname, "../../../../docs/spec/schemas");
+function loadSchema(filename) {
+    const content = readFileSync(resolve(schemasDir, filename), "utf-8");
+    return JSON.parse(content);
+}
+const SCHEMA_MAP = {
+    "euconform.report.v1": { schemaFile: "report-v1.schema.json", type: "report.v1" },
+    "euconform.aibom.v1": { schemaFile: "aibom-v1.schema.json", type: "aibom.v1" },
+    "euconform.aibom.v1.1": { schemaFile: "aibom-v1.1.schema.json", type: "aibom.v1.1" },
+    "euconform.ci.v1": { schemaFile: "ci-v1.schema.json", type: "ci.v1" },
+    "euconform.bundle.v1": { schemaFile: "bundle-v1.schema.json", type: "bundle.v1" },
+};
+let ajvInstance = null;
+function getAjv() {
+    if (!ajvInstance) {
+        ajvInstance = new Ajv2020({ allErrors: true, strict: false });
+        addFormats(ajvInstance);
+    }
+    return ajvInstance;
+}
+export function validate(data, _options) {
+    if (typeof data !== "object" || data === null) {
+        return {
+            valid: false,
+            schemaType: "report.v1",
+            errors: [
+                {
+                    path: "",
+                    message: "Input must be a JSON object",
+                    keyword: "type",
+                    expected: "object",
+                    received: typeof data,
+                },
+            ],
+        };
+    }
+    const record = data;
+    const schemaVersion = record.schemaVersion;
+    if (typeof schemaVersion !== "string") {
+        return {
+            valid: false,
+            schemaType: "report.v1",
+            errors: [
+                {
+                    path: "",
+                    message: `Missing or invalid schemaVersion field. Expected one of: ${Object.keys(SCHEMA_MAP).join(", ")}`,
+                    keyword: "required",
+                },
+            ],
+        };
+    }
+    const entry = SCHEMA_MAP[schemaVersion];
+    if (!entry) {
+        return {
+            valid: false,
+            schemaType: "report.v1",
+            errors: [
+                {
+                    path: "/schemaVersion",
+                    message: `Unknown schemaVersion "${schemaVersion}". Expected one of: ${Object.keys(SCHEMA_MAP).join(", ")}`,
+                    keyword: "const",
+                    expected: Object.keys(SCHEMA_MAP),
+                    received: schemaVersion,
+                },
+            ],
+        };
+    }
+    const ajv = getAjv();
+    let validateFn = ajv.getSchema(schemaVersion);
+    if (!validateFn) {
+        const schema = loadSchema(entry.schemaFile);
+        validateFn = ajv.compile({ ...schema, $id: schemaVersion });
+    }
+    const valid = validateFn(data);
+    if (valid) {
+        return { valid: true, schemaType: entry.type, errors: [] };
+    }
+    const errors = (validateFn.errors ?? []).map((err) => ({
+        path: err.instancePath ?? "",
+        message: err.message ?? "Validation error",
+        keyword: err.keyword ?? "unknown",
+        expected: err.params,
+        received: undefined,
+    }));
+    return { valid: false, schemaType: entry.type, errors };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@euconform/core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "license": "MIT OR EUPL-1.2",
   "author": "Benedikt Hiepler",
   "description": "Core engine for EU AI Act compliance, risk classification, and fairness metrics.",
@@ -30,7 +30,9 @@
     "./types": "./src/types.ts",
     "./scanner": "./src/scanner/index.ts",
     "./evidence": "./src/evidence/index.ts",
-    "./datasets": "./src/datasets/crows-pairs.ts"
+    "./datasets": "./src/datasets/crows-pairs.ts",
+    "./validation": "./src/validation/index.ts",
+    "./sbom": "./src/sbom/index.ts"
   },
   "devDependencies": {
     "@types/node": "^22.15.30",
@@ -41,6 +43,8 @@
   },
   "dependencies": {
     "@xenova/transformers": "^2.17.2",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
     "ignore": "^7.0.3"
   },
   "scripts": {

package/src/evidence/output.ts

@@ -81,6 +81,7 @@ const SOURCE_PRIORITY: Record<BomComponent["source"], number> = {
   config: 4,
   code: 3,
   "lock-file": 2,
+  "sbom-import": 2,
   docs: 1,
 };
 

package/src/evidence/types.ts

@@ -232,11 +232,17 @@ export interface BomComponent {
   kind: BomComponentKind;
   name: string;
   version?: string;
-  source: "package.json" | "lock-file" | "code" | "config" | "docs";
+  source: "package.json" | "lock-file" | "code" | "config" | "docs" | "sbom-import";
+}
+
+export interface AibomMetadata {
+  importSource: "cyclonedx" | "spdx" | "manual";
+  importTool?: string;
+  originalTimestamp?: string;
 }
 
 export interface AiBillOfMaterials {
-  schemaVersion: "euconform.aibom.v1";
+  schemaVersion: "euconform.aibom.v1" | "euconform.aibom.v1.1";
   generatedAt: string;
   project: {
     name: string;
@@ -251,6 +257,7 @@ export interface AiBillOfMaterials {
     humanReviewFlow: boolean;
     incidentHandling: boolean;
   };
+  metadata?: AibomMetadata;
 }
 
 // ---------------------------------------------------------------------------

package/src/evidence/validate.ts

@@ -7,10 +7,16 @@ function assertObject(data: unknown, label: string): Record<string, unknown> {
   return data as Record<string, unknown>;
 }
 
-function requireSchemaVersion(obj: Record<string, unknown>, expected: string, label: string): void {
-  if (obj.schemaVersion !== expected) {
+function requireSchemaVersion(
+  obj: Record<string, unknown>,
+  expected: string | string[],
+  label: string
+): void {
+  const allowed = Array.isArray(expected) ? expected : [expected];
+  if (!allowed.includes(obj.schemaVersion as string)) {
+    const quoted = allowed.map((v) => `"${v}"`).join(" or ");
     throw new Error(
-      `Invalid ${label} schema version: expected "${expected}", got "${String(obj.schemaVersion)}"`
+      `Invalid ${label} schema version: expected ${quoted}, got "${String(obj.schemaVersion)}"`
     );
   }
 }
@@ -102,7 +108,7 @@ export function validateScanReport(data: unknown): ScanReport {
 
 export function validateAiBillOfMaterials(data: unknown): AiBillOfMaterials {
   const obj = assertObject(data, "AIBOM");
-  requireSchemaVersion(obj, "euconform.aibom.v1", "AIBOM");
+  requireSchemaVersion(obj, ["euconform.aibom.v1", "euconform.aibom.v1.1"], "AIBOM");
   requireField(obj, "generatedAt", "string", "AIBOM");
 
   const project = requireField(obj, "project", "object", "AIBOM") as Record<string, unknown>;
@@ -289,6 +295,7 @@ export function validateEcefJsonDocument(
     case "euconform.report.v1":
       return validateScanReport(data);
     case "euconform.aibom.v1":
+    case "euconform.aibom.v1.1":
       return validateAiBillOfMaterials(data);
     case "euconform.ci.v1":
       return validateCiReport(data);

package/src/sbom/component-mapper.ts

@@ -0,0 +1,107 @@
+import type { BomComponentKind } from "../evidence/types";
+import { lookupKnownPackage } from "./known-packages";
+import { parsePurl } from "./purl";
+import type { CycloneDxComponent } from "./types";
+
+export interface ComponentMapping {
+  kind: BomComponentKind;
+  source: "sbom-import";
+  confidence: "high" | "medium";
+  purlVersion?: string;
+}
+
+const CYCLONEDX_TYPE_MAP: Record<
+  string,
+  { kind: BomComponentKind; confidence: "high" | "medium" }
+> = {
+  "machine-learning-model": { kind: "model", confidence: "high" },
+  data: { kind: "dataset", confidence: "medium" },
+  platform: { kind: "inference-provider", confidence: "medium" },
+  service: { kind: "inference-provider", confidence: "medium" },
+};
+
+/** Tiers 7-8: Try to find a kind via purl namespace/name and name-only lookups. */
+function lookupViaPurl(
+  parsed: ReturnType<typeof parsePurl>
+): { kind: BomComponentKind; confidence: "high" | "medium" } | null {
+  if (!parsed) return null;
+
+  // Tier 7: namespace/name (e.g. @langchain/core)
+  if (parsed.namespace) {
+    const scopedName = `${parsed.namespace}/${parsed.name}`;
+    const scopedKind = lookupKnownPackage(scopedName);
+    if (scopedKind) return { kind: scopedKind, confidence: "high" };
+  }
+
+  // Tier 8: purl name only
+  const purlKind = lookupKnownPackage(parsed.name);
+  if (purlKind) return { kind: purlKind, confidence: "medium" };
+
+  return null;
+}
+
+/**
+ * Map a CycloneDX component to an EuConform aibom component kind.
+ *
+ * 8-tier detection (descending priority):
+ * 1. ML-BOM extensions (modelCard, data)
+ * 2. CycloneDX component type mapping
+ * 3. Exact package name in registry
+ * 4. Explicit scoped name in registry (@langchain/core)
+ * 5. Scope mapping via KNOWN_AI_SCOPES (@langchain -> tool)
+ * 6. Scope-stripped name in registry (@huggingface/transformers -> transformers)
+ * 7. Purl namespace/name against registry
+ * 8. Purl name-only against registry
+ *
+ * Steps 3-6 are handled by lookupKnownPackage().
+ * Returns null if the component is not AI-relevant or has empty name.
+ */
+export function mapComponent(component: CycloneDxComponent): ComponentMapping | null {
+  // Name validation
+  if (!component.name || component.name.trim() === "") {
+    return null;
+  }
+
+  // Extract purl info (used for fallback and version)
+  const parsed = component.purl ? parsePurl(component.purl) : null;
+  const purlVersion = parsed?.version;
+
+  // Tier 1: ML-BOM extensions
+  if (component.modelCard != null) {
+    return { kind: "model", source: "sbom-import", confidence: "high", purlVersion };
+  }
+
+  if (Array.isArray(component.data) && component.data.some((d) => d.type === "dataset")) {
+    return { kind: "dataset", source: "sbom-import", confidence: "high", purlVersion };
+  }
+
+  // Tier 2: CycloneDX component type
+  const typeMapping = CYCLONEDX_TYPE_MAP[component.type];
+  if (typeMapping) {
+    return {
+      kind: typeMapping.kind,
+      source: "sbom-import",
+      confidence: typeMapping.confidence,
+      purlVersion,
+    };
+  }
+
+  // Tiers 3-6: Known-package registry (handles exact, scoped, scope-fallback, scope-stripped)
+  const knownKind = lookupKnownPackage(component.name);
+  if (knownKind) {
+    return { kind: knownKind, source: "sbom-import", confidence: "high", purlVersion };
+  }
+
+  // Tiers 7-8: Purl fallback
+  const purlMatch = lookupViaPurl(parsed);
+  if (purlMatch) {
+    return {
+      kind: purlMatch.kind,
+      source: "sbom-import",
+      confidence: purlMatch.confidence,
+      purlVersion,
+    };
+  }
+
+  return null;
+}

package/src/sbom/cyclonedx-import.ts

@@ -0,0 +1,198 @@
+import { basename, extname } from "node:path";
+import type { AiBillOfMaterials, AibomMetadata, BomComponent } from "../evidence/types";
+import type { ValidationResult } from "../validation/schema-validator";
+import { validate } from "../validation/schema-validator";
+import { mapComponent } from "./component-mapper";
+import type { CycloneDxBom } from "./types";
+import { SUPPORTED_SPEC_VERSIONS } from "./types";
+
+export interface ImportWarning {
+  component: string;
+  message: string;
+}
+
+export interface ImportSourceInfo {
+  bomFormat: "CycloneDX";
+  specVersion: string;
+  projectNameSource: "metadata.component.name" | "sourcePath" | "fallback";
+  importTool?: string;
+  originalTimestamp?: string;
+}
+
+export interface ImportSummary {
+  totalComponents: number;
+  filteredByScope: number;
+  aiRelevant: number;
+  skipped: number;
+  duplicatesRemoved: number;
+  byKind: Record<string, number>;
+  warnings: ImportWarning[];
+  source: ImportSourceInfo;
+}
+
+export interface ImportOptions {
+  scope?: "all" | "production";
+  sourcePath?: string;
+}
+
+export interface CycloneDxImportResult {
+  aibom: AiBillOfMaterials;
+  summary: ImportSummary;
+  validation: ValidationResult;
+}
+
+export function importCycloneDx(sbom: unknown, options?: ImportOptions): CycloneDxImportResult {
+  const bom = parseBom(sbom);
+  const scope = options?.scope ?? "all";
+
+  const allComponents = bom.components ?? [];
+  const warnings: ImportWarning[] = [];
+  const totalComponents = allComponents.length;
+
+  const inScope =
+    scope === "production"
+      ? allComponents.filter((c) => c.scope !== "optional" && c.scope !== "excluded")
+      : allComponents;
+  const filteredByScope = totalComponents - inScope.length;
+
+  const mapped: BomComponent[] = [];
+  for (const comp of inScope) {
+    const mapping = mapComponent(comp);
+    if (!mapping) {
+      if (!comp.name || comp.name.trim() === "") {
+        warnings.push({ component: "(empty)", message: "Skipped: missing or empty name" });
+      }
+      continue;
+    }
+
+    const version = comp.version || mapping.purlVersion;
+    if (!version) {
+      warnings.push({ component: comp.name, message: "Missing version field" });
+    }
+
+    mapped.push({
+      id: version ? `${mapping.kind}:${comp.name}:${version}` : `${mapping.kind}:${comp.name}`,
+      kind: mapping.kind,
+      name: comp.name,
+      ...(version ? { version } : {}),
+      source: "sbom-import",
+    });
+  }
+
+  const seen = new Set<string>();
+  let duplicatesRemoved = 0;
+  const deduped: BomComponent[] = [];
+  for (const comp of mapped) {
+    if (seen.has(comp.id)) {
+      duplicatesRemoved++;
+      continue;
+    }
+    seen.add(comp.id);
+    deduped.push(comp);
+  }
+
+  const byKind: Record<string, number> = {};
+  for (const comp of deduped) {
+    byKind[comp.kind] = (byKind[comp.kind] ?? 0) + 1;
+  }
+
+  const { projectName, projectNameSource } = resolveProjectName(bom, options?.sourcePath);
+  const importTool = extractToolString(bom);
+  const originalTimestamp = bom.metadata?.timestamp;
+
+  const aibom: AiBillOfMaterials = {
+    schemaVersion: "euconform.aibom.v1.1",
+    generatedAt: new Date().toISOString(),
+    project: { name: projectName, rootPath: "." },
+    components: deduped,
+    complianceCapabilities: {
+      biasEvaluation: false,
+      jsonExport: false,
+      pdfExport: false,
+      loggingInfrastructure: false,
+      humanReviewFlow: false,
+      incidentHandling: false,
+    },
+    metadata: buildMetadata(importTool, originalTimestamp),
+  };
+
+  const validation = validate(aibom);
+
+  return {
+    aibom,
+    summary: {
+      totalComponents,
+      filteredByScope,
+      aiRelevant: deduped.length,
+      skipped: inScope.length - mapped.length,
+      duplicatesRemoved,
+      byKind,
+      warnings,
+      source: buildSourceInfo(bom.specVersion, projectNameSource, importTool, originalTimestamp),
+    },
+    validation,
+  };
+}
+
+function resolveProjectName(
+  bom: CycloneDxBom,
+  sourcePath?: string
+): { projectName: string; projectNameSource: ImportSourceInfo["projectNameSource"] } {
+  const metaName = bom.metadata?.component?.name;
+  if (metaName) {
+    return { projectName: metaName, projectNameSource: "metadata.component.name" };
+  }
+
+  if (sourcePath) {
+    const name = basename(sourcePath, extname(sourcePath));
+    return { projectName: name, projectNameSource: "sourcePath" };
+  }
+
+  return { projectName: "sbom-import", projectNameSource: "fallback" };
+}
+
+function extractToolString(bom: CycloneDxBom): string | undefined {
+  const tool = bom.metadata?.tools?.[0];
+  if (!tool?.name) return undefined;
+  return tool.version ? `${tool.name} ${tool.version}` : tool.name;
+}
+
+function buildMetadata(importTool?: string, originalTimestamp?: string): AibomMetadata {
+  const meta: AibomMetadata = { importSource: "cyclonedx" };
+  if (importTool) meta.importTool = importTool;
+  if (originalTimestamp) meta.originalTimestamp = originalTimestamp;
+  return meta;
+}
+
+function buildSourceInfo(
+  specVersion: string,
+  projectNameSource: ImportSourceInfo["projectNameSource"],
+  importTool?: string,
+  originalTimestamp?: string
+): ImportSourceInfo {
+  const info: ImportSourceInfo = { bomFormat: "CycloneDX", specVersion, projectNameSource };
+  if (importTool) info.importTool = importTool;
+  if (originalTimestamp) info.originalTimestamp = originalTimestamp;
+  return info;
+}
+
+function parseBom(sbom: unknown): CycloneDxBom {
+  if (typeof sbom !== "object" || sbom === null) {
+    throw new Error("Input must be a JSON object");
+  }
+
+  const record = sbom as Record<string, unknown>;
+
+  if (record.bomFormat !== "CycloneDX") {
+    throw new Error(`Invalid bomFormat: expected "CycloneDX", got "${String(record.bomFormat)}"`);
+  }
+
+  const specVersion = String(record.specVersion ?? "");
+  if (!SUPPORTED_SPEC_VERSIONS.includes(specVersion as (typeof SUPPORTED_SPEC_VERSIONS)[number])) {
+    throw new Error(
+      `Unsupported specVersion "${specVersion}". Supported: ${SUPPORTED_SPEC_VERSIONS.join(", ")}`
+    );
+  }
+
+  return sbom as CycloneDxBom;
+}

package/src/sbom/index.ts

@@ -0,0 +1,12 @@
+export {
+  importCycloneDx,
+  type CycloneDxImportResult,
+  type ImportSummary,
+  type ImportWarning,
+  type ImportOptions,
+  type ImportSourceInfo,
+} from "./cyclonedx-import";
+export { mapComponent, type ComponentMapping } from "./component-mapper";
+export { lookupKnownPackage, KNOWN_AI_PACKAGES, KNOWN_AI_SCOPES } from "./known-packages";
+export { parsePurl, type ParsedPurl } from "./purl";
+export type { CycloneDxBom, CycloneDxComponent } from "./types";