From baa9734965477fa41fb8b8733117e2ba626ce44d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Feb 2026 06:15:43 +0000 Subject: [PATCH 1/7] Add CLAUDE.md with project conventions and build instructions https://claude.ai/code/session_01LQddmhPjeEKJMGyx8ZZVcw --- CLAUDE.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..4b67246e6 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,96 @@ +# CLAUDE.md + +## Project Overview + +graphql-java is a production-ready Java implementation of the [GraphQL specification](https://spec.graphql.org/). It focuses strictly on GraphQL execution — JSON parsing, HTTP, and database access are out of scope. + +## Build System + +Gradle with wrapper. Always use `./gradlew`. + +```bash +./gradlew build # Full build (compile + test + checks) +./gradlew test # Run all tests +./gradlew check # All verification tasks +./gradlew javadoc # Generate Javadoc +``` + +Build caching and parallel execution are enabled by default. + +## Java Version + +- **Build toolchain**: Java 21 +- **Target/release**: Java 11 (source and bytecode compatibility) +- CI tests on Java 11, 17, and 21 + +## Testing + +- **All tests are written in [Spock](https://spockframework.org/) (Groovy)**. Write new tests in Spock, not JUnit. +- Test sources: `src/test/groovy/graphql/` +- Test resources: `src/test/resources/` +- JMH benchmarks: `src/jmh/` + +Run tests: +```bash +./gradlew test +``` + +## Code Style and Conventions + +Formatting follows `graphql-java-code-style.xml` (IntelliJ). Full guidelines are in `coding-guidelines.md`. Key rules: + +- **No wildcard imports** — use explicit imports only +- **Max 2 levels of indentation** — extract methods to reduce nesting +- **Early method exit** — return early instead of wrapping in `if(!cond)` +- **No inner classes** — every class gets its own file +- **Immutable data classes** with Builder pattern and `transform()` method +- Builder factory method: `newFoo()` (not `newBuilder()`). Builder setters: `foo(value)` (not `setFoo(value)`) +- **Use `graphql.Assert`** instead of `Objects.requireNonNull` +- **Use `@Public` and `@Internal`** annotations for API stability. Never use package-private or protected — use public + `@Internal` +- **No Optional** — use nullable values instead (legacy decision for consistency) +- Default collections: `ArrayList`, `LinkedHashSet`, `LinkedHashMap` +- Dependencies as instance fields with `@VisibleForTesting` for testability +- Static methods only for simple utils with no dependencies +- Keep streams simple — no nested stream maps; extract inner logic to methods +- Public API methods take `FooEnvironment` argument objects for future compatibility + +## Nullability + +JSpecify annotations with NullAway (via ErrorProne) in strict mode. Public API classes annotated with `@PublicApi` should use `@Nullable` from `org.jspecify.annotations` for nullable parameters and return types. + +## Dependencies + +**No new dependencies.** This is a firm project policy — dependency conflicts make adoption harder for users. + +## Project Structure + +``` +src/main/java/graphql/ # Main source +src/main/antlr/ # ANTLR grammar files (GraphQL parser) +src/test/groovy/graphql/ # Spock tests (mirrors main structure) +src/test/java/ # Additional Java tests +src/jmh/ # JMH performance benchmarks +``` + +Key packages under `graphql/`: +- `execution/` — query execution engine +- `language/` — AST definitions +- `parser/` — ANTLR-based parser +- `schema/` — GraphQL schema types and validation +- `validation/` — query validation +- `normalized/` — query normalization +- `introspection/` — introspection support +- `scalar/` — built-in scalar types + +## Pre-commit Hooks + +Set up local hooks with: +```bash +./scripts/setup-hooks.sh +``` + +Hooks check for Windows-incompatible filenames and files over 10MB. + +## CI + +GitHub Actions. PRs run build + test on Java 25 (Corretto) and verify Javadoc generation. File validation checks run on all PRs. From 30fc7e2a28f9e60f511d49dec887d12d5be74065 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Mar 2026 07:49:44 +0000 Subject: [PATCH 2/7] Condense CLAUDE.md to reduce context window usage Keep only actionable constraints and conventions; remove discoverable info (project structure, CI, pre-commit hooks). https://claude.ai/code/session_01LQddmhPjeEKJMGyx8ZZVcw --- CLAUDE.md | 107 +++++++----------------------------------------------- 1 file changed, 14 insertions(+), 93 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4b67246e6..f4f629165 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,96 +1,17 @@ # CLAUDE.md -## Project Overview - -graphql-java is a production-ready Java implementation of the [GraphQL specification](https://spec.graphql.org/). It focuses strictly on GraphQL execution — JSON parsing, HTTP, and database access are out of scope. - -## Build System - -Gradle with wrapper. Always use `./gradlew`. - -```bash -./gradlew build # Full build (compile + test + checks) -./gradlew test # Run all tests -./gradlew check # All verification tasks -./gradlew javadoc # Generate Javadoc -``` - -Build caching and parallel execution are enabled by default. - -## Java Version - -- **Build toolchain**: Java 21 -- **Target/release**: Java 11 (source and bytecode compatibility) -- CI tests on Java 11, 17, and 21 - -## Testing - -- **All tests are written in [Spock](https://spockframework.org/) (Groovy)**. Write new tests in Spock, not JUnit. -- Test sources: `src/test/groovy/graphql/` -- Test resources: `src/test/resources/` -- JMH benchmarks: `src/jmh/` - -Run tests: -```bash -./gradlew test -``` - -## Code Style and Conventions - -Formatting follows `graphql-java-code-style.xml` (IntelliJ). Full guidelines are in `coding-guidelines.md`. Key rules: - -- **No wildcard imports** — use explicit imports only -- **Max 2 levels of indentation** — extract methods to reduce nesting -- **Early method exit** — return early instead of wrapping in `if(!cond)` -- **No inner classes** — every class gets its own file -- **Immutable data classes** with Builder pattern and `transform()` method -- Builder factory method: `newFoo()` (not `newBuilder()`). Builder setters: `foo(value)` (not `setFoo(value)`) -- **Use `graphql.Assert`** instead of `Objects.requireNonNull` -- **Use `@Public` and `@Internal`** annotations for API stability. Never use package-private or protected — use public + `@Internal` -- **No Optional** — use nullable values instead (legacy decision for consistency) +Java GraphQL spec implementation. Build: `./gradlew build|test|check|javadoc`. Java 21 toolchain, targets Java 11. + +## Rules + +- **Tests in Spock (Groovy)**, not JUnit: `src/test/groovy/graphql/` +- **No new dependencies** (firm policy) +- **No wildcard imports**, no inner classes, no `Optional` +- Max 2 indent levels; early returns; extract methods to reduce nesting +- Immutable data classes w/ Builder: `newFoo()` factory, `foo(value)` setters, `transform()` method +- Use `graphql.Assert` not `Objects.requireNonNull` +- Use `@Public`/`@Internal` annotations — never package-private/protected +- JSpecify `@Nullable` on public API; NullAway enforced via ErrorProne - Default collections: `ArrayList`, `LinkedHashSet`, `LinkedHashMap` -- Dependencies as instance fields with `@VisibleForTesting` for testability -- Static methods only for simple utils with no dependencies -- Keep streams simple — no nested stream maps; extract inner logic to methods -- Public API methods take `FooEnvironment` argument objects for future compatibility - -## Nullability - -JSpecify annotations with NullAway (via ErrorProne) in strict mode. Public API classes annotated with `@PublicApi` should use `@Nullable` from `org.jspecify.annotations` for nullable parameters and return types. - -## Dependencies - -**No new dependencies.** This is a firm project policy — dependency conflicts make adoption harder for users. - -## Project Structure - -``` -src/main/java/graphql/ # Main source -src/main/antlr/ # ANTLR grammar files (GraphQL parser) -src/test/groovy/graphql/ # Spock tests (mirrors main structure) -src/test/java/ # Additional Java tests -src/jmh/ # JMH performance benchmarks -``` - -Key packages under `graphql/`: -- `execution/` — query execution engine -- `language/` — AST definitions -- `parser/` — ANTLR-based parser -- `schema/` — GraphQL schema types and validation -- `validation/` — query validation -- `normalized/` — query normalization -- `introspection/` — introspection support -- `scalar/` — built-in scalar types - -## Pre-commit Hooks - -Set up local hooks with: -```bash -./scripts/setup-hooks.sh -``` - -Hooks check for Windows-incompatible filenames and files over 10MB. - -## CI - -GitHub Actions. PRs run build + test on Java 25 (Corretto) and verify Javadoc generation. File validation checks run on all PRs. +- Public API methods take `FooEnvironment` arg objects +- Full style guide: `coding-guidelines.md` From d5f01977b8bf60c95fce322fe28fc043ff873db8 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Mar 2026 08:58:18 +0000 Subject: [PATCH 3/7] Include @NonNull alongside @Nullable in JSpecify rule https://claude.ai/code/session_01LQddmhPjeEKJMGyx8ZZVcw --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index f4f629165..aaf68edaa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ Java GraphQL spec implementation. Build: `./gradlew build|test|check|javadoc`. J - Immutable data classes w/ Builder: `newFoo()` factory, `foo(value)` setters, `transform()` method - Use `graphql.Assert` not `Objects.requireNonNull` - Use `@Public`/`@Internal` annotations — never package-private/protected -- JSpecify `@Nullable` on public API; NullAway enforced via ErrorProne +- JSpecify nullability (`@Nullable`/`@NonNull`) on public API; NullAway enforced via ErrorProne - Default collections: `ArrayList`, `LinkedHashSet`, `LinkedHashMap` - Public API methods take `FooEnvironment` arg objects - Full style guide: `coding-guidelines.md` From b7a0440c8bb043f16cc0ef7c17e564e59a71d5ca Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Mar 2026 08:59:02 +0000 Subject: [PATCH 4/7] Update JSpecify rule: @NullMarked on all public API classes https://claude.ai/code/session_01LQddmhPjeEKJMGyx8ZZVcw --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index aaf68edaa..687e3394a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ Java GraphQL spec implementation. Build: `./gradlew build|test|check|javadoc`. J - Immutable data classes w/ Builder: `newFoo()` factory, `foo(value)` setters, `transform()` method - Use `graphql.Assert` not `Objects.requireNonNull` - Use `@Public`/`@Internal` annotations — never package-private/protected -- JSpecify nullability (`@Nullable`/`@NonNull`) on public API; NullAway enforced via ErrorProne +- `@NullMarked` on all public API classes; use `@Nullable` for nullable params/returns; NullAway enforced via ErrorProne - Default collections: `ArrayList`, `LinkedHashSet`, `LinkedHashMap` - Public API methods take `FooEnvironment` arg objects - Full style guide: `coding-guidelines.md` From ce0be71f4c0cf0c083b2eecb87fdc61f9495dff7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Mar 2026 23:08:52 +0000 Subject: [PATCH 5/7] Add @NullUnmarked rule for Builder classes in public API https://claude.ai/code/session_01LQddmhPjeEKJMGyx8ZZVcw --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 687e3394a..2946eaf7e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ Java GraphQL spec implementation. Build: `./gradlew build|test|check|javadoc`. J - Immutable data classes w/ Builder: `newFoo()` factory, `foo(value)` setters, `transform()` method - Use `graphql.Assert` not `Objects.requireNonNull` - Use `@Public`/`@Internal` annotations — never package-private/protected -- `@NullMarked` on all public API classes; use `@Nullable` for nullable params/returns; NullAway enforced via ErrorProne +- `@NullMarked` on all public API classes; `@NullUnmarked` on their Builder classes; use `@Nullable` for nullable params/returns; NullAway enforced via ErrorProne - Default collections: `ArrayList`, `LinkedHashSet`, `LinkedHashMap` - Public API methods take `FooEnvironment` arg objects - Full style guide: `coding-guidelines.md` From 7e4df6dd399de831711f0421f6943a2f206b2458 Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Sun, 8 Mar 2026 10:15:36 +1100 Subject: [PATCH 6/7] Update agents file --- AGENTS.md | 12 +++++++++++- CLAUDE.md | 17 ----------------- 2 files changed, 11 insertions(+), 18 deletions(-) delete mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 369e771d6..dd1611e12 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,16 @@ # AI Agent Context for graphql-java -This file provides context for AI assistants working with this codebase. +## Rules + +- **Tests in Spock (Groovy)**, not JUnit: `src/test/groovy/graphql/` +- **No new dependencies** (firm policy) +- **No wildcard imports**, no inner classes, no `Optional` +- Max 2 indent levels; early returns; extract methods to reduce nesting +- Immutable data classes w/ Builder: `newFoo()` factory, `foo(value)` setters, `transform()` method +- Use `graphql.Assert` not `Objects.requireNonNull` +- Use `@Public`/`@Internal` annotations — never package-private/protected +- `@NullMarked` on all public API classes; use `@Nullable` for nullable params/returns; NullAway enforced via ErrorProne +- Full style guide: `coding-guidelines.md` ## Test Execution diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 687e3394a..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,17 +0,0 @@ -# CLAUDE.md - -Java GraphQL spec implementation. Build: `./gradlew build|test|check|javadoc`. Java 21 toolchain, targets Java 11. - -## Rules - -- **Tests in Spock (Groovy)**, not JUnit: `src/test/groovy/graphql/` -- **No new dependencies** (firm policy) -- **No wildcard imports**, no inner classes, no `Optional` -- Max 2 indent levels; early returns; extract methods to reduce nesting -- Immutable data classes w/ Builder: `newFoo()` factory, `foo(value)` setters, `transform()` method -- Use `graphql.Assert` not `Objects.requireNonNull` -- Use `@Public`/`@Internal` annotations — never package-private/protected -- `@NullMarked` on all public API classes; use `@Nullable` for nullable params/returns; NullAway enforced via ErrorProne -- Default collections: `ArrayList`, `LinkedHashSet`, `LinkedHashMap` -- Public API methods take `FooEnvironment` arg objects -- Full style guide: `coding-guidelines.md` From 15b06cda5bcfceda9a1a27a1985650697cbec1a7 Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Sun, 8 Mar 2026 10:16:00 +1100 Subject: [PATCH 7/7] Ignore scheduled tasks --- .gitignore | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 24e536c80..0875f31c4 100644 --- a/.gitignore +++ b/.gitignore @@ -16,4 +16,5 @@ docs/_build/ /.nb-gradle/ gen .DS_Store -.vscode \ No newline at end of file +.vscode +.claude/scheduled_tasks.lock \ No newline at end of file