generate-scalardb-code

Files (1)

• SKILL.md

SKILL.md (first lines)

# ScalarDB Code Generation

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

## Desired Outcome

Generate per-service Java code from design and implementation specifications:
- Entity classes (ScalarDB Result mapping)
- Repository implementations (Get/Put/Scan/Delete operations)
- Domain services (including transaction management)
- Spring Boot configuration (scalardb.properties, Config classes)
- Gradle build configuration (build.gradle)
- Dockerfile

## Package Ownership (the seam)

This skill owns the **domain and persistence** layers. The API layer — controllers, request/response
DTOs, mappers, Bean Validation, and the RFC 9457 exception handler — is generated by
`/architect:generate-api-code` from the OpenAPI contract, and the two must not overwrite each other:

| Package | Owner |
|---------|-------|
| `…/domain/`, `…/infrastructure/` | **this skill** |
| `…/api/` | `/architect:generate-api-code` |
| `…/application/` (`…/usecase/` when `api-layer-spec.md` declares `layering_style: clean`) | this skill writes the implementation — the application service body, or under `clean` the `<Operation>Interactor` implementing the input boundary and calling the output boundary (recovery, saga and worker use cases have no output boundary and return `void` or a domain-free result record); plus, under either style, the transaction runner (`…/tx/`), the read models (`…/view/`), the workers and relays (`…/worker/`), and the shared collaborators that a split into interactors leaves behind (assemblers, settlement steps, resolvers) — non-interactor classes in the same package, called only from it. The interface and the controller's call to it come from `generate-api-code`. **On a style switch** this skill performs the migration: move `application/` to `usecase/`, split the services into the interactors the specification names (never re-derive the logic), delete the replaced services, move their tests, and repair every artifact that still names `..application..` — the JaCoCo includes, the ArchUnit rules, the component scan, the `api/` handler's imports — reporting each edit to a file another skill owns |
| `…/domain/port/` (outbound ports to other services) + their Fakes | this skill |
| `…/infrastructure/client/` (HTTP / gRPC adapters implementing those outbound ports) | `/architect:generate-api-code` — it owns the HTTP surface in both directions, binding each client to the *other* service's contract; until it runs the application service is wired to the Fakes behind a `@ConditionalOnMissingBean` |

Run both for a complete service. Emitting a controller here would produce a second, unbound API
surface — the exact drift @rules/api-contract-fidelity.md exists to prevent.

## Knowledge Grounding

Before writing any ScalarDB API call, config key, or exception handler, resolve the OKF knowledge
bundle and pin the target ScalarDB version/edition per @rules/okf-knowledge-bundle.md. The
`implement`-phase concepts of that release (`api-guide.md`, `configurations.md`,
`scalardb-samples/`) are the authority for API signatures, property names, and retryability of
each exception; the local pattern rules below supply code shape but the pinned bundle wins on any
disagreement.

## Deprecation Check (mandatory)

After resolving the ScalarDB version, verify the deprecation status of every ScalarDB API the
design commits to **against the resolved artifact** (e.g. `javap` on the jar from the Gradle
cache) or the pinned release notes in the OKF bundle — not against the pattern templates, which
are dated examples. Do not carry a deprecation claim over from this document either: the
application-driven 2PC surface (`TwoPhaseCommitTransactionManager`, `TwoPhaseCommitTransaction`,
`getTwoPhaseCommitTransactionManager()`) was previously described here as `@Deprecated` on 3.19+,
and that is **not** what the pinned bundle says — `two-phase-commit-transactions.md` is
`status: stable` on 3.19 (@rules/scalardb-2pc-patterns.md). The check stands; the presumed answer
does not. Using a deprecated API deliberately (recorded design
deviation) requires `@SuppressWarnings("deprecation")` scoped to the smallest element, an
in-code comment naming the deviation and the non-deprecated migration path, and a line in the
run summary. Unexplained deprecation warnings in the build output are a defect, not noise.

## Dependency Versions

`build.gradle` and the `Dockerfile` pin versions, so follow @rules/dependency-versions.md before
writing them: resolve the current ScalarDB (edition-appropriate), Spring Boot, Java, and base-image
versions from their registries, pick the **stable** ones that are mutually compatible, and never copy
the illustrative numbers out of @rules/spring-boot-integration.md or
`@skills/common/references/code-patterns/` — those are dated examples. Present the version decision
table for confirmation per `--confirm-versions` / `--no-confirm-versions` /
`options.confirm_versions`, and record it in `work/version-decisions.json` plus the run summary —
`/architect:generate-docs` then picks the pins up from the emitted build files when it writes the
service docs, so do not hand-write a competing table inside its marked sections.

## Acceptance Criteria

- Fully compliant with patterns in @rules/scalardb-coding-patterns.md
- API usage, config keys, and exception retryability verified against the pinned release's docs in the OKF bundle (@rules/okf-knowledge-bundle.md)
- Applies configuration patterns from @rules/spring-boot-integration.md
- Under `layering_style: clean`: every input boundary has exactly one interactor, `usecase/` imports nothing from `api/` or `infrastructure/`, no `application/` package remains after a migration, and every artifact that named it (JaCoCo, ArchUnit, component scan) was repaired
- Proper handling of transaction exceptions (retry, rollback)
- Entities follow immutable design; value objects are immutable
- Domain tests import nothing from `infrastructure/`, ScalarDB or Spring; every repository port has an
  in-memory Fake; `Clock` and id generation are injected (@rules/tdd-workflow.md §4)
- Every `TX-` entry has an `*IT` over the in-process engine covering its happy path, OCC conflict and
  blind write, plus 2PC / saga scenarios where the design uses them; `./gradlew integrationTest` was
  run, matched tests, and passed
- Every pinned version was looked up (not recalled), is a stable release, and is recorded in the
  version decision table — with the user's confirmation when that is the configured mode

## Prerequisites

| File | Required/Recommended | Source |
|------|---------------------|--------|
| reports/06_implementation/ | Required | /architect:design-implementation |
| reports/03_design/scalardb-schema.md | Required | /architect:design-scalardb |
| reports/03_design/scalardb-transaction.md | Required | /architect:design-scalardb — the `TX-` entries the integration suite is generated from |
| reports/07_test-specs/integration-test-specs.md | Recommended | /architect:generate-test-specs — the transaction scenarios per `TX-` |
| reports/07_test-specs/ | Recommended | /architect:generate-test-specs |
| reports/07_test-specs/property-test-specs.md | Recommended when an aggregate manifest exists | /architect:generate-test-specs — the property per invariant this skill turns into a jqwik test |
| reports/03_design/aggregates/aggregate-manifest.json | Optional | /architect:design-aggregate — invariants enforced in the root, and the examples the unit tests replay |

## Domain Tests

Emit the domain layer's tests alongside it, under `generated/{service}/src/test/java/**/domain/`:

- **Example tests** — one JUnit 5 test method per `positive` / `negative` example in the aggregate
  manifest, replaying `given` / `when` / `then` against the root, named after the invariant and
  the example so a failure reads as the design row it contradicts.
- **Property tests** — one jqwik `@Property` per invariant, exactly as
  `property-test-specs.md` specifies it: an `Arbitrary` per value object honouring its validation
  rule (one class per value object under `**/domain/arbitraries/`, shared across invariants), the
  aggregate generator composed from them, each `violated_by` command applied with `@ForAll`
  arguments, and the assertion *invariant holds or command rejected*. Drive the root; never a
  service.
- **Build** — add `jqwik` (JUnit 5 platform engine) to `build.gradle` `testImplementation`, with
  its version **looked up** and recorded in the version decision table like every other pin
  (@rules/dependency-versions.md); register the engine with JUnit 5 so `./gradlew test` runs the
  properties, and set `tries` per property from the spec (default 1000) so stage 2's evidence
  records a non-zero case count. Apply the `jacoco` plugin with a `jacocoTestCoverageVerification`
  rule per package (90 % line / 80 % branch on `domain/` and `application/` — `usecase/` under
  `clean` — 70 % line elsewhere,
  exemptions by package pattern) and the `pitest` plugin (`junit5` plugin engine, `targetClasses`
  = the domain packages, threshold 80), so the quality gate's stage 2 has named tasks to run
  (@rules/ai-code-quality-gate.md §Test quality) — both plugin versions looked up, never recalled.

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect