llms.txt

# ReadingBat Java Content

> A content repository defining Java and Kotlin programming challenges for the ReadingBat platform.

This repository provides interactive coding challenges served by [readingbat-core](https://github.com/readingbat/readingbat-core). It is not a standalone application — it defines challenge content using a Kotlin DSL.

## Structure

- `src/main/kotlin/Content.kt`: Central DSL file declaring all challenges by language, group, and package
- `src/main/kotlin/ContentServer.kt`: Server entry point (delegates to readingbat-core)
- `src/main/java/<package>/*.java`: Java challenge files (each a class with a static method and main())
- `src/main/kotlin/<package>/*.kt`: Kotlin challenge files (top-level functions with main())
- `src/test/kotlin/ContentTests.kt`: Kotest suite validating all challenges via a Ktor test host
- `.gitattributes`: line-ending normalization — LF in the repository, `*.bat` checked out CRLF, `*.jar` binary

## Challenge Convention

Each challenge is a standalone source file. The `main()` function prints expected outputs which become the answer key. Java challenges use a `@desc` comment for descriptions. The class or file name must match what is declared in `Content.kt`, and Kotlin challenges require an explicit `returnType` (e.g. `IntType`, `StringType`, `IntListType`) — either per-challenge or via `includeFilesWithType`.

## Tech Stack

- Kotlin / JVM, Gradle (Kotlin DSL) with a version catalog. The JVM toolchain version is centralized in `gradle/libs.versions.toml` under the `jvm` key.
- readingbat-core (platform library, from JitPack)
- Kotest + Ktor test host (testing)
- detekt + kotlinter (static analysis and formatting, enforced in CI)

## Common Commands

Run `make help` for the authoritative target list.

- `make build` — compile without running tests
- `make tests` — run all tests
- `make lint` — run kotlinter and detekt
- `make format` — format Kotlin sources
- `make run` — start the content server on http://localhost:8080
- `make uberjar` — build fat jar at `build/libs/server.jar`
- `make uber` — build uberjar and run it
- `make versions` — check for dependency updates
- `./gradlew test -Dkotest.filter.tests="<name>"` — filter Kotest cases by name

## Testing

`ContentTests.kt` sweeps the catalog one language at a time (`Test all Java challenges`, `Test all Kotlin challenges`) through a shared `verifyAllChallenges` helper: empty answers must report `NOT_ANSWERED`, wrong answers `INCORRECT`, and each challenge's `main()` output `CORRECT`.

Two constraints are easy to break when editing the suite:
- The sweeps await `runTestApplication` directly rather than calling `testApplication`. `testApplication` is `runTestWithRealTime { runTestApplication(..) }`, and that wrapper imposes `runTest`'s 60s default — a ceiling a Kotest `TestConfig(timeout = ..)` cannot raise. Awaiting the inner entry point leaves the declared 5-minute timeout as the only limit.
- The sweeps name `content.java` and `content.kotlin` explicitly, so a new language in `Content.kt` needs its own sweep. The `Per-language tests cover every challenge` case fails the suite as a reminder.

## Versioning

Releases are tagged (`1.0.0` onward) with the version tracked in `gradle.properties`. See `CHANGELOG.md` for the dated history and `RELEASE_NOTES.md` for narrative milestones.

## Local vs Production

The DSL in `Content.kt` swaps the `repo` source based on `isProduction()`:
- Local dev uses `FileSystemSource("./")` — challenge files load directly from disk, so edits are picked up on reload without a rebuild.
- Production uses `GitHubRepo` — content is fetched from the GitHub repository.