This commit is contained in:
NotAlexNoyle committed 2026-05-25 11:15:47 -04:00
1 parent 5802034fa5
commit ffd9d33a52
3 files changed
+12 -107

No files matched your search

+7 -8
View File
@@ -19,14 +19,13 @@ out
builds
target
META-INF
/build/
/.gradle/
build/
.kotlin/
.gradle/
.gradle-user/
/.gradle-cache/
/.gradle-local/
.gradle-cache/
.gradle-local/
kls-classpath
kls_database.db
/run/
/bin/
.opencode/
run/
bin/
-99
View File
@@ -1,99 +0,0 @@
# AGENTS.md
**Prime directive:** If you are reading this file, it is your responsibility as an agent to keep it up to date with any changes you make in this repository.
This file holds always-on repository guidance and routing hints. Detailed workflows and historical notes live in repo-local agent skills under `.agents/skills/`.
## Always-on rules
- Use British English spelling and phraseology at all times.
- Do **not** use American English spelling or phraseology.
- Use conventional commit format.
- Keep commits subject-only unless the user explicitly asks for a body.
- Release Please renders commit subjects into changelog entries, so subjects must be release-note-friendly and comprehensible without the type prefix or body.
- Prefer scoped subjects where useful, such as `feat(config): add default modesets for unlisted worlds`.
- For issue, ticket, or bug-report driven work, include the ticket number in the commit subject, such as `fix(modesets): correct stale stored world modesets (#865)`.
- Avoid vague subjects such as `feat: support ...`, `feat: migrate ...`, or `test: cover ...` when a clearer user-facing summary is possible.
- Root and user-facing agents must not open or read `build/integration-test-logs/*.log` directly. Log inspection is allowed only by subagents, and only when needed for integration-test triage or when explicitly requested. Prefer compact console summaries and `plugins/OldCombatMechanicsTest/test-failures.txt` first.
- Never hard-code absolute filesystem paths in tests or production code; resolve locations relative to the repo root, plugin data folder, or server run directory.
- Prefer feature detection over hard-coded Minecraft version gates because server implementations may backport APIs.
- For NMS/reflection access, prefer the project `utilities.reflection.Reflector` helpers over ad-hoc reflection where practical.
- Reflection should be a compatibility fallback, not the first choice on hot paths.
- For optional methods on already-present Bukkit types, especially in hot paths, prefer direct calls with cached `NoSuchMethodError` or narrow linkage fallbacks over reflective invocation. Use reflection when classes, parameter or return types, signatures, NMS shapes, or cross-version linkage would make direct calls unsafe.
- Do not gate plugin behaviour on assumptions from one Paper/Spigot version without checking compatible API presence.
- Agents must not disable, skip, weaken, or version-gate tests as a way to make validation pass. Fix failing tests at the root cause, or report the failure as a blocker unless the user explicitly approves a coverage reduction.
## Repo overview
- Project: OldCombatMechanics, a Bukkit/Paper plugin.
- Branch context: working from `kotlin-tests`.
- Build tool: Gradle wrapper, currently 9.2.1.
- JDKs used locally: 8, 11, 17, 25.
- Main integration tests live in `src/integrationTest/kotlin` and are packaged into `OldCombatMechanics-<version>-tests.jar`.
- Entrypoint test plugin class: `kernitus.plugin.OldCombatMechanics.OCMTestMain`.
- PacketEvents is shaded into the main plugin; integration tests resolve PacketEvents from that shaded copy rather than injecting a separate external packet library.
## Build and validation quick reference
- Full integration matrix: `./gradlew integrationTest`.
- Selected versions: `./gradlew integrationTest -PintegrationTestVersions=1.19.2,1.21.11,1.12`.
- Matrix task examples: `integrationTest1_19_2`, `integrationTest1_21_11`, `integrationTest1_12`, `integrationTest1_9`.
- Java toolchain override example: `ORG_GRADLE_JAVA_INSTALLATIONS_PATHS=/path/to/jdk8:/path/to/jdk17:/path/to/jdk25 ./gradlew integrationTest`.
- `checkTestResults<version>` fails the build if `plugins/OldCombatMechanicsTest/test-results.txt` is missing or not `PASS`.
- `KotestRunner` writes a compact `plugins/OldCombatMechanicsTest/test-failures.txt` summary for CI-friendly failure triage.
## Skill selection guide
- **Mandatory trigger:** Use `dependabot-pr-review` for Dependabot PRs, dependency bumps, Gradle/Maven dependency updates, GitHub Actions version updates, dependency changelog/licence/release-note review, and dependency validation recommendations. Other skills remain relevant for deeper integration-test selection (`integration-test-verification`), compatibility strategy (`compatibility-strategy`), and release-readiness concerns (`release-readiness-review`).
- **Mandatory trigger:** Use `github-issue-investigation` for GitHub issue triage, `gh issue` investigation, picking a fresh issue, reproducing issue reports, or identifying durable regression coverage. Do not use it for GitHub-side mutation or implementation once the investigation is complete.
- **Mandatory trigger:** Use `integration-test-verification` for integration-test runs, matrix selection, compact failure triage, Kotlin integration test authoring, or `KotestRunner` registration questions. Do not use it for ordinary unit-free source edits with no test-harness impact.
- **Mandatory trigger:** Use `compatibility-strategy` for Java 8 compatibility, Bukkit/Paper version differences, NMS/reflection, fake players, PacketEvents compatibility, feature detection, or legacy-server fallbacks. Do not use it for release notes or configuration-only routing.
- **Mandatory trigger:** Use `module-config-change` for `config.yml`, module enablement, modesets, migrations, configurable module assignment, or per-module settings such as tool damage, attack cooldown, attack range, or sword blocking options. Do not use it for pure test execution or release publishing.
- **Mandatory trigger:** Use `commit-preparation` for preparing commits, pre-commit hooks, Spotless, formatting or linting, validation before commit, staging files, and conventional commit messages. Do not use it for implementation design or PR prose unless commit readiness is also in scope.
- **Mandatory trigger:** Use `release-readiness-review` for GitHub release, Hangar, CurseForge/BukkitDev, licence, workflow, supported-version, or release asset checks. Do not use it for feature implementation unless the change affects release packaging.
- **Mandatory trigger:** Use `pr-draft-summary` when drafting PR descriptions, change summaries, reviewer notes, or risk/test sections. Do not use it while still deciding implementation strategy.
## Current project state
- Paper 1.12 integration tests do not yet run the full fake-player test suite; legacy fake-player work needs a dedicated or version-aware NMS path.
- Java 8 compatibility is required for main code. Avoid APIs such as records, pattern matching, `Stream.toList()`, and `Set.of`/`List.of` in Java 8-targeted code.
- Main Java/Kotlin compilation targets Java 8 (`options.release.set(8)`, Kotlin `jvmTarget = 1.8`).
- Pre-1.13 integration-test versions use `integrationTestJavaVersionLegacyPre13` (default 8); modern versions use Java 25 for `>=1.20.5` and Java 17 otherwise.
- Legacy vanilla jars for `<=1.12` are downloaded by `downloadVanilla<version>` into `run/<version>/cache/mojang_<version>.jar`.
## Core implementation constraints
- Module assignment is strict for configurable modules at top-level category scope: every non-internal module must appear in at most one of `always_enabled_modules`, `disabled_modules`, or the aggregate `modesets` category. A module may appear in more than one individual modeset because modesets are alternative player modes.
- Internal modules (`modeset-listener`, `attack-cooldown-tracker`, `entity-damage-listener`) are always enabled and must not be listed in configurable module groups.
- Reload/enable must fail for invalid module assignment rather than silently choosing a fallback.
- Modules are enabled/disabled solely via `always_enabled_modules`, `disabled_modules`, and `modesets`; there is no per-module `enabled:` toggle.
- When adding new integration test specs, add them to the explicit `.withClasses(...)` list in `KotestRunner` because autoscan is disabled.
- New classes should be written in Kotlin by default where practical, matching `.github/CONTRIBUTING.md`.
## Integration test essentials
- Tests run inside a real Paper server started by the Gradle `run-paper` plugin.
- RunServer output is redirected to `build/integration-test-logs/<version>.log`; root and user-facing agents must leave any needed log inspection to subagents after compact summaries and `plugins/OldCombatMechanicsTest/test-failures.txt` prove insufficient.
- Kotlin tests use Kotest 6 for Java 11+ server targets (`KotestRunner`, `KotestProjectConfig`).
- Java 8 targets use `LegacyTestRunner`, currently a smoke-test path rather than the full Kotest suite.
- Several integration tests intentionally use synthetic Bukkit events or direct module handler calls. Consult `integration-test-verification` before assuming a test represents a real in-world action.
## Historical notes index
- Detailed relocated history from the former long `AGENTS.md` lives in `.agents/skills/integration-test-verification/references/relocated-agents-notes.md`.
- Dependabot, dependency bump, changelog, licence, JVM/classfile, GitHub Actions, and validation recommendation reviews: `dependabot-pr-review`.
- GitHub issue triage, `gh issue` investigation, fresh issue shortlisting, reproduction recommendations, and regression coverage notes: `github-issue-investigation`.
- Integration harness, fake-player, PacketEvents, and test-shortcut details: `integration-test-verification` and its references.
- Compatibility, Java 8, reflection, NMS, and version strategy details: `compatibility-strategy`.
- Module configuration, modeset, migration, and option-change details: `module-config-change`.
- Commit preparation, pre-commit hooks, Spotless, staging, validation-before-commit, and conventional commit details: `commit-preparation`.
- Publishing, release workflow, licence, and asset notes: `release-readiness-review`.
- PR summary templates and reviewer-facing change grouping: `pr-draft-summary`.
## TDAID reminders (this repo)
- Plan → Red → Green → Refactor → Validate.
- Red phase: only touch tests.
- Green phase: only touch production code.
- Refactor phase: clean-ups only; keep behaviour unchanged and tests green.
- Validate phase: rerun the narrowest relevant tests and do a human sanity check before declaring done.
+5
View File
@@ -236,6 +236,11 @@ tasks.test {
useJUnitPlatform()
}
tasks.jar {
// The runtime plugin is the shaded jar below; do not emit an unbundled plugin artefact.
enabled = false
}
val shadowJarTask =
tasks.named<ShadowJar>("shadowJar") {
dependsOn("jar")