Feature/schema validator cyclonedx imp

.changeset/schema-validator-cyclonedx-import.md

@@ -0,0 +1,12 @@
+---
+"@euconform/core": minor
+"@euconform/cli": minor
+---
+
+Add schema validation, CycloneDX SBOM import, and AI BOM v1.1 schema revision
+
+- Introduce `euconform.aibom.v1.1` schema with optional import provenance metadata
+- Add `validate` command for checking EuConform JSON documents against published schemas
+- Add `import` command for mapping CycloneDX JSON SBOMs into the EuConform AI BOM layer
+- Add PURL parser with graceful handling of malformed percent-encoding
+- Remove `validate` and `importCycloneDx` from core barrel export (available via `@euconform/core/validation` and `@euconform/core/sbom` subpath exports)

README.md

@@ -1,12 +1,12 @@
 <h1 align="center">EuConform</h1>
 
 <p align="center">
-  <strong>🇪🇺 Open-Source EU AI Act Compliance Tool</strong>
+  <strong>🇪🇺 Open-Source Evidence Toolkit For AI Compliance</strong>
 </p>
 
 <p align="center">
-  Classify risk levels • Detect algorithmic bias • Generate compliance reports<br>
-  <em>100% offline • GDPR-by-design • WCAG 2.2 AA accessible</em>
+  Open evidence format • Local bias evaluation • Schema validation • CycloneDX interoperability<br>
+  <em>Offline-first • Privacy-preserving • Reusable artifacts • WCAG 2.2 AA accessible</em>
 </p>
 
 <p align="center">
@@ -34,6 +34,10 @@
   </a>
 </p>
 
+<p align="center">
+  EuConform defines an open evidence format for AI compliance and provides the tools to produce, validate, and empirically evaluate it — offline and vendor-independent.
+</p>
+
 ---
 
 > [!IMPORTANT]
@@ -59,17 +63,29 @@
 
 | Feature | Description |
 |---------|-------------|
-| 🎯 **Risk Classification** | Interactive quiz implementing EU AI Act Article 5 (prohibited), Article 6 + Annex III (high-risk) |
-| 📊 **Bias Detection** | CrowS-Pairs methodology with log-probability analysis for scientific bias measurement |
-| 📄 **PDF Reports** | Generate Annex IV-compliant technical documentation entirely in-browser |
+| 🧾 **Open Evidence Format** | Produce portable `report`, `aibom`, `ci`, and `bundle` artifacts as inspectable JSON documents |
+| 🧪 **Local Bias Evaluation** | CrowS-Pairs-based model evaluation with log-probability and latency fallback — reproducible, offline, no vendor dependency |
+| ✅ **Schema Validation** | Validate EuConform JSON documents against the published schemas with `euconform validate` |
+| 📦 **Bundle Verification** | Verify manifest, directory, or ZIP bundle integrity before handing artifacts to CI, reviewers, or auditors |
 | 🚦 **Compliance CI Gate** | Turn `euconform scan` into GitHub-native annotations, CI summaries, and machine-readable artifacts |
-| 🌐 **100% Offline** | All processing happens client-side using transformers.js (WebGPU) |
-| 🔒 **Privacy-First** | Zero tracking, no cookies, no external fonts – your data never leaves your browser |
-| 📤 **Custom Test Suites** | Upload your own CSV/JSON test cases for domain-specific bias evaluation |
+| 🎯 **Risk Classification** | Interactive quiz implementing EU AI Act Article 5 (prohibited), Article 6 + Annex III (high-risk) |
+| 🔄 **CycloneDX Interoperability** | Import external CycloneDX SBOMs into the EuConform AI BOM layer as an interoperability bridge |
+| 🌐 **Offline-First** | Core evidence workflows stay local and inspectable instead of depending on vendor dashboards |
+| 🔒 **Privacy-Preserving** | Zero tracking, no cookies, no external fonts – your data stays under your control |
 | 🌙 **Dark Mode** | Beautiful glassmorphism design with full dark mode support |
 | ♿ **Accessible** | WCAG 2.2 AA compliant with full keyboard navigation |
 | 🌍 **Multilingual** | English and German interface |
 
+## 🧰 CLI At A Glance
+
+| Command | Primary output | Use case |
+|---------|----------------|----------|
+| `scan` | Native EuConform artifacts | Generate structured evidence from a real repository |
+| `bias` | Bias report JSON and/or Markdown | Run reproducible local model evaluation with Ollama — EuConform's distinctive empirical layer |
+| `validate` | Valid/invalid status per JSON file | Check EuConform JSON files against published schemas |
+| `verify` | Bundle integrity status | Check a manifest, extracted bundle, or ZIP archive |
+| `import` | `euconform.aibom.json` | Map an external CycloneDX SBOM into the EuConform AI BOM layer |
+
 ## 🚀 Quick Start
 
 > **Want to try it without installation?** Click the [**🌐 Deploy**](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FHiepler%2FEuConform&project-name=euconform&repository-name=euconform) link above to start your own instance on Vercel.
@@ -97,15 +113,20 @@ pnpm dev
 # Open http://localhost:3001
 ```
 
-### CLI Scanner
+### Build The CLI
 
-The local scanner turns EuConform into a reproducible evidence tool for real repositories:
+The repo-local examples below use the built CLI directly:
 
 ```bash
 # Build the CLI
 pnpm --filter @euconform/cli build
+```
+
+### Workflow 1: Scan A Repository
+
+Generate native EuConform artifacts from a real codebase:
 
-# Scan the current project
+```bash
 node packages/cli/dist/index.js scan . --scope production
 ```
 
@@ -115,6 +136,11 @@ This writes:
 - `.euconform/euconform.summary.md`
 - `.euconform/euconform.bundle.json`
 
+Typical use:
+- evidence collection for local OSS or internal AI projects
+- CI gating and reviewer handoff
+- portable artifact generation without a vendor platform
+
 For CI usage, add GitHub-native annotations and fail thresholds:
 
 ```bash
@@ -127,12 +153,65 @@ For portable artifact exchange, create a bundle archive:
 node packages/cli/dist/index.js scan . --scope production --zip true
 ```
 
+### Workflow 2: Validate And Verify Existing Artifacts
+
+Validate individual EuConform JSON documents against the published schemas:
+
+```bash
+node packages/cli/dist/index.js validate .euconform
+```
+
+Typical output:
+- one line per file such as `euconform.aibom.json — valid (euconform.aibom.v1)`
+- exit code `0` for fully valid input, `1` for schema errors, `2` when no EuConform JSON files are found
+
 Verify a bundle manifest, extracted bundle directory, or ZIP archive:
 
 ```bash
 node packages/cli/dist/index.js verify .euconform/euconform.bundle.json
 ```
 
+Typical use:
+- reviewer-side schema checking before manual analysis
+- CI sanity checks for artifact sets already produced elsewhere
+- portability checks before sharing bundles with downstream tools
+
+### Workflow 3: Evaluate Model Bias Locally
+
+Run a reproducible CrowS-Pairs bias evaluation against a local Ollama model:
+
+```bash
+node packages/cli/dist/index.js bias llama3.2 --lang de --output all
+```
+
+This is EuConform's distinctive empirical evidence layer. It produces model-behavior data that no other open-source compliance tool currently offers — completely offline, reproducible, and independent of any vendor API.
+
+Typical use:
+- empirical model-behavior evidence for Art. 10 bias/fairness documentation
+- reproducible local evaluation before and after model updates
+- adding a behavioral evidence layer on top of structural evidence from `scan`
+
+### Workflow 4: Import An External CycloneDX SBOM
+
+Map an external CycloneDX JSON file into the EuConform AI BOM layer:
+
+```bash
+node packages/cli/dist/index.js import ./third-party.cdx.json \
+  --scope production \
+  --output /tmp/euconform-import
+
+node packages/cli/dist/index.js validate /tmp/euconform-import/euconform.aibom.json
+```
+
+This writes:
+- `/tmp/euconform-import/euconform.aibom.json`
+
+Important notes:
+- `import` accepts CycloneDX JSON and maps only the AI-relevant subset into `euconform.aibom.v1.1`
+- `--scope production` excludes `optional` and `excluded` components
+- the importer is intentionally conservative and does **not** infer compliance capabilities from an SBOM
+- project naming may come from BOM metadata or the source filename, depending on the input
+
 ### Try The Format In 10 Minutes
 
 If you want to evaluate the current adoption path as an OSS builder, use one of the
@@ -193,10 +272,14 @@ Supports Llama, Mistral, and Qwen variants with automatic log-probability detect
 
 ### CLI Scanner & CI
 
-`euconform scan` is designed to complement the web wizard:
-- The **scanner** gathers technical evidence from a real codebase.
-- The **web app** remains the place for role and risk classification with human context.
-- The **bias evaluation tooling** adds empirical model-behavior evidence on top.
+EuConform's CLI is designed as reusable evidence infrastructure:
+- `euconform scan` produces native EuConform artifacts from a repository.
+- `euconform bias` provides EuConform's distinctive empirical model-behavior evidence layer.
+- `euconform validate` checks individual EuConform JSON files against the published schemas.
+- `euconform verify` checks artifact-set integrity for manifests, directories, and ZIP bundles.
+- `euconform import` bridges external CycloneDX JSON into the EuConform AI BOM layer.
+
+The **web app** remains the place for role and risk classification with human context.
 
 #### GitHub Actions Example
 
@@ -215,13 +298,19 @@ In GitHub Actions, EuConform emits:
 
 ### EuConform Evidence Format
 
-The scanner artifacts are defined as the **EuConform Evidence Format**, an open specification for offline AI Act evidence exchange.
+EuConform implements the **EuConform Evidence Format**, an open specification for portable, machine-readable AI compliance evidence.
 
 - `euconform.report.v1` captures compliance evidence, gaps, and open questions
 - `euconform.aibom.v1` is the AI Bill of Materials (AI BOM) inventory layer
 - `euconform.ci.v1` captures CI thresholds, status, and top findings
 - `euconform.bundle.v1` binds artifact sets into a portable, integrity-aware manifest
 
+Current workflow boundaries:
+- `scan` **produces** native EuConform artifacts from source repositories
+- `import` can **ingest** external CycloneDX JSON into the current AIBOM layer for interoperability workflows
+- `validate` makes the schema and compatibility story inspectable at the JSON-document level
+- `verify` checks portable bundle integrity before exchange or automation
+
 Stage 1 documentation, schemas, and example artifacts live in [docs/spec/README.md](docs/spec/README.md).
 Reference source projects for OSS builders live in [examples/README.md](examples/README.md).
 

apps/docs/public/schemas/spec/aibom-v1.1.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://euconform.eu/schemas/spec/aibom-v1.1.schema.json",
+  "title": "EuConform Evidence Format AI BOM v1.1",
+  "description": "Stage 1 inventory document for AI-relevant components and compliance capabilities. Adds optional import provenance metadata.",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "project", "components", "complianceCapabilities"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": "euconform.aibom.v1.1"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "project": {
+      "type": "object",
+      "required": ["name", "rootPath"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "rootPath": { "type": "string" }
+      }
+    },
+    "components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "name", "source"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "kind": {
+            "enum": [
+              "framework",
+              "runtime",
+              "inference-provider",
+              "ai-framework",
+              "model",
+              "vector-store",
+              "embedding",
+              "dataset",
+              "tool"
+            ]
+          },
+          "name": { "type": "string" },
+          "version": { "type": "string" },
+          "source": {
+            "enum": ["package.json", "lock-file", "code", "config", "docs", "sbom-import"]
+          }
+        }
+      }
+    },
+    "complianceCapabilities": {
+      "type": "object",
+      "required": [
+        "biasEvaluation",
+        "jsonExport",
+        "pdfExport",
+        "loggingInfrastructure",
+        "humanReviewFlow",
+        "incidentHandling"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "biasEvaluation": { "type": "boolean" },
+        "jsonExport": { "type": "boolean" },
+        "pdfExport": { "type": "boolean" },
+        "loggingInfrastructure": { "type": "boolean" },
+        "humanReviewFlow": { "type": "boolean" },
+        "incidentHandling": { "type": "boolean" }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "importSource": {
+          "enum": ["cyclonedx", "spdx", "manual"]
+        },
+        "importTool": {
+          "type": "string"
+        },
+        "originalTimestamp": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

apps/docs/public/schemas/spec/aibom-v1.schema.json

@@ -47,7 +47,7 @@
           "name": { "type": "string" },
           "version": { "type": "string" },
           "source": {
-            "enum": ["package.json", "lock-file", "code", "config", "docs"]
+            "enum": ["package.json", "lock-file", "code", "config", "docs", "sbom-import"]
           }
         }
       }

docs/spec/README.md

@@ -1,6 +1,6 @@
 # EuConform Evidence Format
 
-The **EuConform Evidence Format** is the open specification behind the scanner artifacts produced by EuConform.
+EuConform implements the **EuConform Evidence Format**, an open specification for portable, machine-readable AI compliance evidence.
 
 ## Document types
 
@@ -10,6 +10,7 @@ The **EuConform Evidence Format** is the open specification behind the scanner a
 |----------|---------|
 | `euconform.report.v1` | Compliance-oriented evidence, open questions, gaps, and recommendations |
 | `euconform.aibom.v1` | AI Bill of Materials (AI BOM) inventory for runtimes, providers, models, and supporting components |
+| `euconform.aibom.v1.1` | AI BOM v1 plus optional import provenance metadata |
 | `euconform.ci.v1` | CI gate status, fail threshold, gap counts, and top findings |
 
 ### Stage 2 — Available
@@ -23,18 +24,34 @@ The **EuConform Evidence Format** is the open specification behind the scanner a
 - the format is currently documented as an **open specification**
 - `AI BOM` is a **sub-specification** inside the format, not the umbrella name
 
+## Interoperability
+
+EuConform supports native artifact generation, empirical model evaluation, and external ingestion:
+
+- `scan` generates native EuConform artifacts from a repository
+- `bias` produces reproducible model-behavior evidence via local CrowS-Pairs evaluation — EuConform's distinctive empirical layer
+- `validate` checks EuConform JSON documents against the published schemas
+- `verify` checks bundle integrity for manifests, extracted directories, and ZIP archives
+- `import` maps external CycloneDX JSON into the AIBOM layer (emits `euconform.aibom.v1.1`) as an interoperability bridge
+
+Important boundaries:
+- `bias` is independent of `scan` and can be used standalone for model evaluation
+- `import` does **not** replace a full native EuConform scan of a repository
+- `validate` and `verify` complement each other: schema checks for individual documents, integrity checks for artifact sets
+
 ## Versioning and compatibility
 
 - `schemaVersion` is the compatibility boundary for every document
 - Schemas enforce `additionalProperties: false` — all fields must be explicitly defined
-- Patch releases must not change document shape
-- Adding new optional fields requires a new schema revision (e.g. `report-v1.1.schema.json`) because strict schemas reject unknown properties
+- Published schema revisions should avoid changing document shape in place
+- When new fields affect document shape or compatibility expectations, prefer a new schema revision (e.g. `report-v1.1.schema.json`) because strict schemas reject unknown properties
 - Major schema changes must use a new `schemaVersion` (e.g. `euconform.report.v2`)
 
 ## Schemas
 
 - [Report schema](./schemas/report-v1.schema.json)
 - [AI BOM schema](./schemas/aibom-v1.schema.json)
+- [AI BOM v1.1 schema](./schemas/aibom-v1.1.schema.json)
 - [CI schema](./schemas/ci-v1.schema.json)
 - [Bundle schema](./schemas/bundle-v1.schema.json)
 
@@ -55,7 +72,9 @@ The **EuConform Evidence Format** is the open specification behind the scanner a
 ## Verification flow
 
 - Build the CLI with `pnpm --filter @euconform/cli build`
-- Generate artifacts with `node packages/cli/dist/index.js scan .`
+- Generate native artifacts with `node packages/cli/dist/index.js scan .`
+- Validate EuConform JSON documents with `node packages/cli/dist/index.js validate <path>`
+- Optionally import a CycloneDX JSON file with `node packages/cli/dist/index.js import <path>`
 - Optionally create a transport archive with `node packages/cli/dist/index.js scan . --zip true`
 - Verify a manifest, bundle directory, or ZIP archive with `node packages/cli/dist/index.js verify <path>`
 - Hash and metadata mismatches are warnings by default and become errors in strict mode