diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8278ed7..1c7ba33 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,6 +31,45 @@ The following rule governs code contributions: - Contributions must be licensed under the [Apache 2.0 License](./LICENSE) - Due to legal reasons, contributors will be asked to accept a Developer Certificate of Origin (DCO) when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/). +## CI and Release + +### CI Checks + +Every pull request to `main` and every push to `main` runs the following checks (see [`.github/workflows/pipeline.yml`](.github/workflows/pipeline.yml)): + +| Job | What it enforces | +|---|---| +| `tests` | Unit tests (`mvn test -P '!with-integration-tests'`) on Java 17 and 21 | +| `integration-tests` | Full integration tests on Java 17 and 21 | +| `local-mtx-tests` | MTX lifecycle tests using a local sidecar (`mvn verify -pl integration-tests/mtx-local/srv`) on Java 17 and 21 | +| `sonarqube-scan` | SonarQube static analysis | +| `codeql` | CodeQL security scanning (`security-extended` queries) on Java/Kotlin and GitHub Actions | +| `blackduck` (main only) | BlackDuck full open-source compliance scan | + +Static analysis runs at **compile time on every build** via Maven plugins configured in the root `pom.xml`: + +- **Spotless** — Google Java Format + SAP license headers (enforced at `process-sources`) +- **SpotBugs** — `effort=Max` (at `process-test-classes`) +- **PMD + CPD** — SAP Cloud SDK ruleset (at `process-test-classes`) +- **Maven Enforcer** — no duplicate dependency versions, requires Maven 3.6.3+ and Java 17+ + +Integration tests live in [`integration-tests/`](integration-tests/README.md) — see that README for test modules, run commands, and profiles. + +### JaCoCo Coverage + +Coverage is aggregated in the `coverage-report/` module using JaCoCo's `report-aggregate` goal. Each feature module runs `prepare-agent` to collect `.exec` data; the `coverage-report` module merges all `.exec` files and generates a single HTML report fed into SonarQube. Coverage thresholds (80% on new code) are enforced by SonarQube in the pipeline. + +To generate the report locally: + +```bash +mvn clean verify +# Report: coverage-report/target/site/jacoco-aggregate/index.html +``` + +### Release + +Releases are triggered by publishing a GitHub Release with a matching tag. The [`release.yml`](.github/workflows/release.yml) workflow gates on two protected environments (`release-approval` then `release`), verifies the POM `revision` matches the tag, runs BlackDuck, builds without integration tests, and deploys to Maven Central with GPG signing. + ## Issues and Planning - We use GitHub issues to track bugs and enhancement requests. diff --git a/README.md b/README.md index b2ec6ec..933180c 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ## About this project -This repository contains a collection of AI plugins for [CAP Java](https://cap.cloud.sap/docs/java/) applications, leveraging [SAP AI Core](https://help.sap.com/docs/sap-ai-core) and the SAP-RPT-1 foundation model. +This repository contains a collection of AI plugins for [CAP Java](https://cap.cloud.sap/docs/java/) applications, leveraging [SAP AI Core](https://help.sap.com/docs/sap-ai-core), the SAP-RPT-1 foundation model, and SAP Document AI. ### Plugins @@ -16,32 +16,17 @@ This repository contains a collection of AI plugins for [CAP Java](https://cap.c ### Starter -For the simplest setup, add the **`cds-starter-ai`** dependency which bundles both plugins: - -```xml - - com.sap.cds - cds-starter-ai - ${cds-ai.version} - -``` - -```json -"dependencies": { - "@cap-js/ai": "^1" -} -``` - -> Note: [`cds-feature-sap-document-ai`](cds-feature-sap-document-ai/README.md) is not part of `cds-starter-ai` yet - it will be added once the plugin supports multi-tenancy. Add it as an explicit dependency in your application if you need it today. +See [`cds-starter-ai`](cds-starter-ai/README.md) for the quickest setup. ## Prerequisites - Java 17+ - CAP Java 4.9+ - Node.js 20+ with `@sap/cds-dk` 9+ (for CDS build tooling) -- An [SAP AI Core](https://help.sap.com/docs/sap-ai-core) service binding (for production use) +- An [SAP AI Core](https://help.sap.com/docs/sap-ai-core) service binding (for `cds-feature-ai-core` and `cds-feature-recommendations`) +- A [SAP Document Information Extraction](https://help.sap.com/docs/document-ai) service binding (for `cds-feature-sap-document-ai`) -Without an AI Core binding the plugins fall back to mock implementations for local development. +Without the respective service binding, each plugin falls back to a mock or degraded mode for local development. ## Samples @@ -54,7 +39,7 @@ mvn clean install # build all modules mvn test # run unit tests ``` -For per-plugin details (configuration, programmatic API, multi-tenancy behaviour) see the individual module READMEs. For integration tests against a real AI Core instance see [`integration-tests/spring`](integration-tests/spring). +For per-plugin details (configuration, programmatic API, multi-tenancy behaviour) see the individual module READMEs. For integration tests against a real AI Core instance see [`integration-tests/`](integration-tests/README.md). ## Support, Feedback, Contributing diff --git a/cds-feature-recommendations/README.md b/cds-feature-recommendations/README.md index 03c0a6f..cb74aa5 100644 --- a/cds-feature-recommendations/README.md +++ b/cds-feature-recommendations/README.md @@ -2,7 +2,7 @@ AI-powered field recommendations for SAP Fiori UIs in CAP Java applications, leveraging SAP AI Core and the SAP-RPT-1 foundation model. -## How It Works +## Features The plugin generically hooks into any draft-enabled entity that has properties with a value help. When a user edits a draft record, the plugin: @@ -98,6 +98,11 @@ annotate Books with { }] } } + +// Opt out a specific field +annotate Books with { + genre @UI.RecommendationState: 0; +} ``` #### Adding the SAP_Recommendations navigation property manually diff --git a/cds-feature-sap-document-ai/README.md b/cds-feature-sap-document-ai/README.md index e7977ba..226cb36 100644 --- a/cds-feature-sap-document-ai/README.md +++ b/cds-feature-sap-document-ai/README.md @@ -9,6 +9,7 @@ A CAP Java plugin that integrates [SAP Document AI](https://help.sap.com/docs/do - [Integration Guide](#integration-guide) - [Usage](#usage) - [CDS Model](#cds-model) +- [Multi-Tenancy](#multi-tenancy) - [Bookshop Sample](#bookshop-sample) - [Running without a Document AI service binding](#running-without-a-die-service-binding) - [Running with a Document AI service binding (hybrid mode)](#running-with-a-die-service-binding-hybrid-mode) @@ -190,7 +191,9 @@ Submit a document via your application. The plugin logs progress at `INFO` level > **Note:** In the current version, document extraction can only be triggered programmatically via event emission, as shown in the [Integration Guide](#integration-guide). Annotation-based triggering (e.g. declaratively marking an entity field or action to trigger extraction) is not yet supported and is planned for a future release. -> **Note:** Multitenancy is not implemented in the current version and is planned for a future release. Until then, the plugin should only be used in single-tenant deployments. +## Multi-Tenancy + +Multi-tenancy is not implemented in the current version and is planned for a future release. The `tenantId` field is stored on the `ExtractionJob` entity as groundwork. ### CDS Model @@ -382,6 +385,13 @@ The plugin communicates with the SAP Document Information Extraction service via --- +## Known Limitations + +- **Multi-tenancy** — not implemented; all jobs run in a single-tenant context. Planned for a future release. +- **Annotation-based triggering** — document extraction can only be initiated programmatically via event emission; declarative triggering is not yet supported. + +--- + ## Monitoring and Logging All plugin log statements are prefixed with `[sap-document-ai]` to facilitate log filtering. The plugin uses SLF4J and is configured through the standard logging framework of the host application. diff --git a/cds-starter-ai/README.md b/cds-starter-ai/README.md new file mode 100644 index 0000000..a98c44a --- /dev/null +++ b/cds-starter-ai/README.md @@ -0,0 +1,49 @@ +# cds-starter-ai + +A zero-source convenience module that bundles all SAP AI plugins for CAP Java into a single dependency. + +## What it includes + +| Module | Scope | Description | +|---|---|---| +| [`cds-feature-ai-core`](../cds-feature-ai-core/README.md) | `compile` | Bridges CAP Java to SAP AI Core — resource groups, deployments, configurations, inference client | +| [`cds-feature-recommendations`](../cds-feature-recommendations/README.md) | `runtime` | AI-powered field recommendations for Fiori Elements draft UIs | + +`cds-feature-sap-document-ai` is currently **not** included as the plugin is not yet fully multi-tenant-ready. It will be added to the starter once MT support is complete. Add it as an explicit dependency if you need it today. + +## Setup + +```xml + + com.sap.cds + cds-starter-ai + ${cds-ai.version} + +``` + +Both plugins auto-register via Java's `ServiceLoader` — no further code changes are required. + +For the Node.js side of `cds-feature-recommendations`, also add the `@cap-js/ai` CDS plugin to your `package.json`: + +```json +{ + "dependencies": { + "@cap-js/ai": "^1" + } +} +``` + +## Prerequisites + +- Java 17+ +- CAP Java 4.9+ +- An [SAP AI Core](https://help.sap.com/docs/sap-ai-core) service binding (for production use) +- A [SAP Document Information Extraction](https://help.sap.com/docs/document-ai) service binding (once `cds-feature-sap-document-ai` is included) + +Without the respective bindings the plugins fall back to mock implementations — useful for local development. + +## Related + +- [SAP AI Core Documentation](https://help.sap.com/docs/sap-ai-core) +- [SAP AI SDK for Java](https://github.com/SAP/ai-sdk-java) +- [`cds-feature-sap-document-ai`](../cds-feature-sap-document-ai/README.md) — standalone document extraction plugin diff --git a/integration-tests/README.md b/integration-tests/README.md index 42a660e..38e4622 100644 --- a/integration-tests/README.md +++ b/integration-tests/README.md @@ -45,7 +45,7 @@ Aggregated code coverage is produced by the `coverage-report/` module at the pro 1. Each module that runs tests has the JaCoCo agent attached (`prepare-agent`), which writes a `target/jacoco.exec` file during test execution. 2. The `coverage-report` module (built last in the reactor) merges all `.exec` files into a single `target/jacoco-merged.exec`. -3. It then generates an aggregated HTML/XML report via `jacoco:report-aggregate` and runs `jacoco:check` against configurable thresholds. +3. It then generates an aggregated HTML/XML report via `jacoco:report-aggregate`. Coverage thresholds are enforced by SonarQube in the pipeline, not by JaCoCo check goals. ### Generating the report @@ -61,12 +61,7 @@ coverage-report/target/site/jacoco-aggregate/index.html ### Thresholds -Per-module thresholds are defined in `coverage-report/pom.xml`: - -| Module | Instruction | Branch | Complexity | -|--------|-------------|--------|------------| -| `cds-feature-ai-core` | 0% | 0% | 0% | -| `cds-feature-recommendations` | 80% | 80% | 80% | +Coverage thresholds are enforced by SonarQube in the CI pipeline (80% on new code). ### Coverage data sources @@ -74,5 +69,6 @@ The merged report combines execution data from: - `cds-feature-ai-core/target/jacoco.exec` (unit tests) - `cds-feature-recommendations/target/jacoco.exec` (unit tests) +- `cds-feature-sap-document-ai/target/jacoco.exec` (unit tests) - `integration-tests/spring/target/jacoco.exec` (integration tests) - `integration-tests/mtx-local/srv/target/jacoco.exec` (MTX integration tests, only when profile is active)