Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/project.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ and GitHub Packages.
`MessageDef` implementations.
- `codegen/tests/` (Gradle path `:codegen-tests`): tests that check the
correctness of code generation; uses Chords code generation.
- `codegen/plugins/`: **separate Gradle project** with ProtoData plugins that
- `codegen/plugins/`: **separate Gradle project** with Spine Compiler plugins that
generate Kotlin extensions for Protobuf messages. It uses a different
toolchain from the root build; see [Build Engineering](skills/build-engineer/SKILL.md).
It is applied to consuming projects through the
Expand Down Expand Up @@ -108,7 +108,7 @@ Gradle dependency chain and its configuration.
| `proto-values/README.md` | Supplementary Protobuf messages and extensions |
| `client/README.md` | Server connectivity facilities |
| `codegen/runtime/README.md` | Codegen runtime ownership |
| `codegen/plugins/README.md` | ProtoData plugin project, requirements, and layout |
| `codegen/plugins/README.md` | Spine Compiler plugin project, requirements, and layout |
| `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` | Contribution policy, distributed by `config/pull` |

Keep usage instructions in the nearest library README and API contracts in
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ review also uses `kotlin-engineer` with the area skill.
`core`, `proto`, and `client`, including the shell, forms, and server-backed UI.
- `model-engineer`: change published model Protobuf declarations and Kotlin
extensions in `proto-values`; `.proto` edits require `AGENTS.md` authorization.
- `codegen-engineer`: implement ProtoData codegen plugins, the codegen runtime,
- `codegen-engineer`: implement Spine Compiler plugins, the codegen runtime,
their generated contracts, internal schemas, and correctness tests.
- `build-engineer`: change root and `codegen/plugins` Gradle builds, `buildSrc`
dependencies, publishing, versions, and generated reports.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/build-engineer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ For `.github/workflows` YAML, use `.agents/skills/ci-engineer/SKILL.md`.

- Two toolchains coexist: the root project uses JDK 11 / Gradle 6.9.4 and the
compiler/library version split documented in `kotlin-engineer`;
`codegen/plugins` uses JDK 17 / Gradle 9.4.x / Kotlin 2.3.20. Keep build
`codegen/plugins` uses JDK 17 / Gradle 9.4.x / Kotlin 2.4.10. Keep build
logic compatible with the owning toolchain.
- Dependency coordinates belong in
`buildSrc/src/main/kotlin/io/spine/internal/dependency/`, one object per
Expand Down
10 changes: 5 additions & 5 deletions .agents/skills/codegen-engineer/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: codegen-engineer
description: >
Chords code generation policy. Use for the ProtoData codegen plugins project,
Chords code generation policy. Use for the Spine Compiler plugins project,
the codegen runtime library, generated MessageField/MessageOneof/MessageDef
contracts, plugin-internal Protobuf declarations, codegen correctness tests,
and codegen Gradle wiring.
Expand All @@ -13,7 +13,7 @@ description: >

Use this skill for code generation work:

- ProtoData plugins under `codegen/plugins/` (a separate Gradle project).
- Spine Compiler plugins under `codegen/plugins/` (a separate Gradle project).
- Plugin-internal schemas: `codegen/plugins/codegen-plugins/src/main/proto/**`.
- The codegen runtime under `codegen/runtime/` (Gradle path `:runtime`):
`MessageField`, `MessageOneof`, `MessageDef`, and related runtime types.
Expand All @@ -29,7 +29,7 @@ that merely consume generated metadata, prefer

## Policy

- `codegen/plugins` targets JDK 17, Gradle 9.4.x, and Kotlin 2.3.20; the root
- `codegen/plugins` targets JDK 17, Gradle 9.4.x, and Kotlin 2.4.10; the root
build targets JDK 11 and Gradle 6.9.4, with the Kotlin version split described
in `.agents/skills/kotlin-engineer/SKILL.md`. Never mix the two toolchains in
one command or assume APIs from one are available in the other.
Expand All @@ -40,7 +40,7 @@ that merely consume generated metadata, prefer
- Treat `.proto` files under `codegen/tests/src/test/proto/**` as generator
fixtures. Change them only to express a code-generation scenario; published
model declarations under `proto-values` belong to `model-engineer`.
- Keep `codegen/plugins/src/main/resources/codegen-workspace` resources
- Keep `codegen/plugins/codegen-plugins/src/main/resources/codegen-workspace` resources
consistent with the build logic that copies `buildSrc` and wrapper files
into them; that workspace is what the Chords Gradle plugin unpacks in
consumer projects.
Expand All @@ -51,7 +51,7 @@ that merely consume generated metadata, prefer

## Generation Flow

The separate `codegen/plugins` build produces ProtoData plugins. The root
The separate `codegen/plugins` build produces Spine Compiler plugins. The root
`publishCodegenPluginsToMavenLocal` task publishes them to Maven local before
the `io.spine.chords` Gradle plugin applies them in a generated workspace.
`modulesWithChordsCodegen` selects the consumers (`proto-values` and
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/docs-reviewer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ because the task asks for a review.
inline links are acceptable when the surrounding file already uses them.
- **Terminology is consistent.** Use one term for the same concept within a
change set: Chords, Compose Multiplatform, Spine Event Engine, Protobuf,
ProtoData, codegen plugins, codegen runtime, application shell.
Spine Compiler, codegen plugins, codegen runtime, application shell.
- **No new orphans.** Added or rewritten paragraphs, list items, and table
cells must not end with a one-word line. Do not require unrelated prose to be
reflowed solely to repair legacy wrapping.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/docs-writer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ claims against the nearest README, build file, workflow, or source file.
- Keep examples small enough to verify and copy; follow class-based KDoc,
including the `Table` and `EntityChooser` examples.
- Use consistent terminology: Chords, Compose Multiplatform, Spine Event
Engine, Protobuf, ProtoData, codegen plugins, codegen runtime, application
Engine, Protobuf, Spine Compiler, codegen plugins, codegen runtime, application
shell, class-based components.
- Name the precise relationship instead of using vague ownership language.
Keep literal API terms and state or resource ownership when that is the contract.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/engineer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ the code being changed:
declarations and Kotlin model extensions under `proto-values`, including
schema evolution and package and file organization.
- `.agents/skills/codegen-engineer/SKILL.md` for the `codegen/plugins`
ProtoData project, the codegen runtime (`codegen/runtime`), codegen
Spine Compiler project, the codegen runtime (`codegen/runtime`), codegen
correctness tests (`codegen/tests`), plugin-internal Protobuf declarations,
generated `MessageField`/`MessageOneof`/`MessageDef` contracts, and codegen
Gradle wiring.
Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/kotlin-engineer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Each of these owns its area; this skill stays out of them:
KDoc style, and the Compose 1.5.12 ceiling.
- `.agents/skills/model-engineer/SKILL.md` — published model Protobuf
declarations and Kotlin model extensions under `proto-values`.
- `.agents/skills/codegen-engineer/SKILL.md` — ProtoData plugins and generated
- `.agents/skills/codegen-engineer/SKILL.md` — Spine Compiler plugins and generated
runtime contracts.
- `.agents/skills/build-engineer/SKILL.md` — Gradle Kotlin DSL, `buildSrc`
coordinates, and publishing.
Expand All @@ -54,7 +54,7 @@ root toolchain covers every module in
`settings.gradle.kts`: `core`, `proto`, `proto-values`, `client`, `runtime`
(at `codegen/runtime`), and `codegen-tests` (at `codegen/tests`) — note that
both `codegen/` subprojects belong to the *root* build. Only
`codegen/plugins` is separate, using **Kotlin 2.3.20** on JDK 17 (its own
`codegen/plugins` is separate, using **Kotlin 2.4.10** on JDK 17 (its own
`kotlinVersion` in `codegen/plugins/buildSrc/build.gradle.kts`).

Everything below about the Kotlin 1.8 language ceiling applies to the root
Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/model-engineer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: >
reviewing, or removing project-owned `.proto` declarations and Kotlin model
extensions located in `proto-values`, organizing Protobuf packages, imports,
and files, or evaluating schema-driven generated-accessor effects. Do not
use for ProtoData plugin, generator, or codegen-runtime implementation; use
use for Spine Compiler plugin, generator, or codegen-runtime implementation; use
`codegen-engineer` for those concerns.
---

Expand All @@ -18,7 +18,7 @@ description: >
`proto-values/src/main/kotlin/**`.
- Keep schema declarations, Kotlin extensions, and schema-driven generated
accessors consistent.
- Use `.agents/skills/codegen-engineer/SKILL.md` for ProtoData plugins,
- Use `.agents/skills/codegen-engineer/SKILL.md` for Spine Compiler plugins,
including plugin-internal Protobuf declarations under
`codegen/plugins/codegen-plugins/src/main/proto/**`, and for generator
behavior, codegen-runtime contracts, and test Protobuf files that exist only
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ See [codegen/plugins](codegen/plugins/README.md) for more details.
Besides the modules for each of the library mentioned above, this repo contains
the following key parts:

- [codegen-plugins](codegen/plugins) — separate Gradle project with ProtoData
- [codegen-plugins](codegen/plugins) — separate Gradle project with Spine Compiler
plugins that generate Kotlin extensions for Proto messages.

See [codegen/plugins/README.md](codegen/plugins/README.md) for detail.
Expand Down
11 changes: 7 additions & 4 deletions codegen/plugins/README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,31 @@
# `codegen-plugins`

A separate Gradle project with ProtoData plugins that generate
A separate Gradle project with Spine Compiler plugins that generate
[MessageField](../runtime/src/main/kotlin/io/spine/chords/runtime/MessageField.kt),
[MessageOneof](../runtime/src/main/kotlin/io/spine/chords/runtime/MessageOneof.kt),
and [MessageDef](../runtime/src/main/kotlin/io/spine/chords/runtime/MessageDef.kt)
implementations for Proto messages. Also, some other useful Kotlin extensions are generated,
e.g. `ValidatingBuilder.messageDef()` that returns the instance of `MessageDef` implementation
for the current message builder.

The separate Gradle project is needed because the `ProtoData` plugins,
The separate Gradle project is needed because the `Spine Compiler` plugins,
which generate the code, require the newer version of Gradle, `9.4.x` at the moment,
and Java 17, comparing to Chords-based projects, which require Gradle version `6.9.x` and Java 11.

### Requirements

- Java 17
- Gradle `9.4.x`
- Kotlin `2.3.20`
- Kotlin `2.4.10`

### How to use

The [Chords Gradle plugin](https://github.com/SpineEventEngine/Chords-Gradle-plugin)
should be used to apply `codegen-plugins` to a project.

The workspace exports only Chords `*Def.kt` files. Consumers generate Protobuf Java and
Kotlin DSL files with their configured Protobuf compiler.

### Resources for the Gradle plugin

The following files are copied to the
Expand All @@ -41,4 +44,4 @@ and the Gradle plugin.

### Modules

* [codegen-plugins](codegen-plugins) — the ProtoData plugins generating the code.
* [codegen-plugins](codegen-plugins) — the Spine Compiler plugins generating the code.
12 changes: 8 additions & 4 deletions codegen/plugins/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,11 @@ buildscript {
doForceVersions(configurations)

dependencies {
classpath(io.spine.dependency.local.McJava.pluginLib)
classpath(io.spine.dependency.local.Compiler.pluginLib)
classpath(io.spine.dependency.local.CoreJvmCompiler.gradlePlugin)
classpath(io.spine.dependency.local.Validation.gradlePluginLib)
classpath(io.spine.dependency.local.Time.gradlePlugin)
classpath(io.spine.dependency.build.Ksp.gradlePlugin)
}
}

Expand All @@ -55,7 +59,6 @@ plugins {
id("net.ltgt.errorprone")
id("detekt-code-analysis")
id("com.google.protobuf")
id("io.spine.protodata") version "0.96.4"
idea
}

Expand All @@ -79,11 +82,12 @@ subprojects {
plugin("detekt-code-analysis")
plugin("com.google.protobuf")
plugin("idea")
plugin("io.spine.mc-java")
plugin("io.spine.core-jvm")
}

dependencies {
Protobuf.libs.forEach { implementation(it) }
implementation(Protobuf.java)
implementation(Protobuf.kotlin)

ErrorProne.apply {
errorprone(core)
Expand Down
53 changes: 2 additions & 51 deletions codegen/plugins/buildSrc/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -37,21 +37,13 @@ repositories {
mavenCentral()
}

/**
* The version of Jackson used by `buildSrc`.
*
* Please keep this value in sync. with `io.spine.internal.dependency.Jackson.version`.
* It's not a requirement, but would be good in terms of consistency.
*/
val jacksonVersion = "2.17.2"

/**
* The version of the Kotlin Gradle plugin.
*
* Please check that this value matches one defined in
* [i o.spine.internal.dependency.Kotlin.version].
*/
val kotlinVersion = "2.3.20"
val kotlinVersion = "2.4.10"

/**
* The version of Guava used in `buildSrc`.
Expand All @@ -64,8 +56,6 @@ val guavaVersion = "33.5.0-jre"
/**
* The version of ErrorProne Gradle plugin.
*
* Please keep in sync. with [io.spine.dependency.build.ErrorProne.GradlePlugin.version].
*
* @see <a href="https://github.com/tbroyer/gradle-errorprone-plugin/releases">
* Error Prone Gradle Plugin Releases</a>
*/
Expand All @@ -79,7 +69,7 @@ val errorPronePluginVersion = "4.2.0"
* @see <a href="https://github.com/google/protobuf-gradle-plugin/releases">
* Protobuf Gradle Plugins Releases</a>
*/
val protobufPluginVersion = "0.9.6"
val protobufPluginVersion = "0.10.0"

/**
* The version of Detekt Gradle Plugin.
Expand All @@ -88,23 +78,10 @@ val protobufPluginVersion = "0.9.6"
*/
val detektVersion = "2.0.0-alpha.1"

/**
* @see [io.spine.dependency.test.Kotest]
*/
val kotestJvmPluginVersion = "0.4.10"

/**
* @see [io.spine.dependency.test.Kover]
*/
val koverVersion = "0.9.1"

/**
* The version of Google Artifact Registry used by `buildSrc`.
*
* The version `2.1.5` is the latest before `2.2.0`, which introduces breaking changes.
*
* @see <a href="https://mvnrepository.com/artifact/com.google.cloud.artifactregistry/artifactregistry-auth-common">
* Google Artifact Registry at Maven</a>
*/
val googleAuthToolVersion = "2.1.5"

Expand Down Expand Up @@ -135,9 +112,6 @@ kotlin {
dependencies {
dependOnAuthCommon()

implementation("com.fasterxml.jackson.core:jackson-databind:$jacksonVersion")
implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-xml:$jacksonVersion")

implementation("com.google.guava:guava:$guavaVersion")
implementation("net.ltgt.gradle:gradle-errorprone-plugin:${errorPronePluginVersion}")

Expand All @@ -150,9 +124,6 @@ dependencies {

// https://github.com/srikanth-lingala/zip4j
implementation("net.lingala.zip4j:zip4j:2.10.0")

implementation("io.kotest:kotest-gradle-plugin:$kotestJvmPluginVersion")
implementation("org.jetbrains.kotlinx:kover-gradle-plugin:$koverVersion")
}

/**
Expand Down Expand Up @@ -180,23 +151,3 @@ fun DependencyHandlerScope.dependOnAuthCommon() {
exclude(group = "com.google.guava")
}
}

dependOnBuildSrcJar()

/**
* Adds a dependency on a `buildSrc.jar`, iff:
* 1) the `src` folder is missing, and
* 2) `buildSrc.jar` is present in `buildSrc/` folder instead.
*
* This approach is used in the scope of integration testing.
*/
fun Project.dependOnBuildSrcJar() {
val srcFolder = this.rootDir.resolve("src")
val buildSrcJar = rootDir.resolve("buildSrc.jar")
if (!srcFolder.exists() && buildSrcJar.exists()) {
logger.info("Adding the pre-compiled 'buildSrc.jar' to 'implementation' dependencies.")
dependencies {
implementation(files("buildSrc.jar"))
}
}
}
Loading
Loading