sangria-graphql/sangria

This system is a GraphQL library for Scala that provides a complete execution engine, including parsing, validation, and schema introspection. It supports multiple Scala versions and integrates with functional effect systems like Cats Effect and Monix for asynchronous and streaming operations. The library also features automatic schema derivation from Scala types and optimized performance for query processing.

14 changes.

The project underwent a major architectural restructuring for version 4.0.0, migrating to a multi-module build with Scala 3 support and separating AST definitions from core execution logic. This period introduced a new composable query execution engine, comprehensive validation infrastructure, and native AST marshalling, while adding experimental features like batch query execution and introspection support.

14 changes.

This period focused on porting the derivation and macro systems to support Scala 3 alongside Scala 2, introducing compile-time GraphQL string interpolation and dual-version macro implementations. Concurrently, the core parser and validation logic were refactored for significant performance gains, including an optimized overlapping fields algorithm and fixed memory allocation issues. The work also expanded ecosystem support by adding experimental Cats Effect integration and comprehensive test suites for streaming and derivation features.

This change introduces the Scala 2-specific macro implementation for Sangria's GraphQL string interpolation syntax. It adds \AstLiftable\ to handle AST node serialization for quasiquotes, \ParseMacro\ to parse GraphQL strings at compile-time, and a \package.scala\ that exposes \gql\, \gqlInp\, \gqlInpDoc\, \graphql\, \graphqlInput\, and \graphqlInputDoc\ string interpolators. This enables compile-time validation and parsing of GraphQL queries and inputs for Scala 2 projects.

modules/core/src/main/scala-2 · high confidence

This change introduces Scala 3-specific macro implementations in the \sangria.macros\ package, enabling compile-time parsing of GraphQL queries and inputs via string interpolation. Users can now use \graphql\, \gql\, \graphqlInput\, \graphqlInputDoc\, and \gqlInpDoc\ string interpolators to generate AST documents and values at compile time, replacing the need for runtime parsing in these contexts. The implementation includes the necessary \ToExpr\ givens to serialize AST nodes into quoted expressions, supporting the full range of GraphQL AST types such as operations, fragments, definitions, and types.

modules/core/src/main/scala-3 · high confidence

Introduces a new \queryAst.scala\ module within the core marshalling package that enables direct serialization and deserialization of GraphQL Query AST nodes. This change provides implicit marshallers and unmarshallers for \ast.Value\, allowing users to convert between GraphQL query strings and internal AST representations without relying on intermediate JSON or other formats. It includes specific implementations for parsing inputs, rendering results, and handling scalar, enum, list, and object node types directly within the AST structure.

modules/core/src/main/scala/sangria/marshalling · high confidence

An experimental \BatchExecutor\ has been added to the core module, enabling the execution of multiple GraphQL operations within a single document. This feature allows users to specify multiple operation names and automatically infers execution order based on dependencies between queries. It introduces support for the \@export\ directive, which lets users save field values from one operation and use them as variables in subsequent operations within the same batch, simplifying data dependency management without requiring explicit variable declarations.

modules/core/src/main/scala/sangria/execution/batch · high confidence

This change introduces a new experimental execution scheme that allows Sangria resolvers to return Cats Effect \IO\ (or any \Async\ effect) instead of \Future\. It adds \IOExecutionScheme\ and a generic \AsyncExecutionScheme\ along with an \AsyncResolver\ that bridges the effect type to Sangria's internal \Future\-based resolution logic via an \AsyncToFuture\ adapter. Users can now write GraphQL resolvers that produce \IO\ values, enabling integration with Cats Effect-based applications while the underlying execution still relies on \Future\ conversion.

modules/cats-effect-experimental/src/main · high confidence

The repository is initialized with essential configuration files, including a \.scalafmt.conf\ file to enforce code formatting (version 3.11.5, Scala 2.13 dialect) and a \.git-blame-ignore-revs\ file to ignore automated formatting commits. The project also includes a \README.md\ with usage examples and badges, a \CHANGELOG.md\ documenting version history, a \.gitignore\ for build artifacts, and a \HOW-TO-RELEASE.md\ guide. The legacy Travis CI configuration (\.travis.yml\) is removed in this initial state.

(repo-wide) · high confidence

The AST module now includes a \SourceMapper\ interface and implementations (\DefaultSourceMapper\, \AggregateSourceMapper\) that allow users to generate human-readable error locations for GraphQL parsing failures. This enables more precise feedback, such as highlighting the exact line and column in the source code where a parse error occurred, which is particularly useful when debugging complex queries or composing documents from multiple sources.

modules/ast · high confidence

The \modules/core/src/main/scala/sangria/validation\ module now provides a complete, rule-based query validation system. This includes a \QueryValidator\ that enforces standard GraphQL validation rules (such as \ValuesOfCorrectType\, \FieldsOnCorrectType\, and \VariablesAreInputTypes\) and introduces a configurable \errorsLimit\ to cap the number of validation errors returned, preventing excessive output. The implementation relies on new supporting components: \TypeInfo\ for tracking schema context during AST traversal, \TypeComparators\ for robust type equality and subtyping checks, and \ValidationContext\ to manage validation state and error accumulation.

modules/core/src/main/scala/sangria/validation · high confidence

This change introduces the core introspection support for the GraphQL schema, adding the \IntrospectionParser\ to parse introspection query results and the \package.scala\ definitions for the standard introspection types (such as \\_\Type\, \\\Field\, \\\Directive\, and \\\_DirectiveLocation\). It enables clients to query schema metadata, including support for interface inheritance, input value deprecation, and repeatable directives, as defined by the GraphQL specification.

modules/core/src/main/scala/sangria/introspection · high confidence

This release introduces a new execution engine built around a \QueryReducer\ trait, which allows for composable, tree-reduction-based analysis of GraphQL queries (such as measuring complexity, depth, or collecting tags) rather than simple traversal. Alongside this architectural shift, a new \DeprecationTracker\ trait is added to the execution context, enabling users to opt-in to logging or tracking of deprecated fields, enum values, directive arguments, and input object fields. The \ExecutionPath\ class has also been refactored to optimize performance by avoiding unnecessary vector allocations during path construction and marshalling.

modules/core/src/main/scala/sangria/execution · high confidence

The derivation module now supports both Scala 2 and Scala 3, providing separate macro implementations in \scala-2\ and \scala-3\ source directories to handle the differences in macro systems (blackbox macros vs. quoted macros). This change introduces new annotation classes (such as \GraphQLName\, \GraphQLDescription\, \GraphQLDeprecated\, \GraphQLFieldTags\, \GraphQLExclude\, \GraphQLField\, \GraphQLDefault\, \GraphQLOutputType\, and \GraphQLInputType\) and type lookup mechanisms (\GraphQLInputTypeLookup\ and \GraphQLOutputTypeLookup\) that enable automatic derivation of GraphQL schema types from Scala case classes and enums. Users can now use the \deriveObjectType\, \deriveInputObjectType\, \deriveContextObjectType\, and \deriveEnumType\ macros in Scala 3 projects, with the Scala 3 versions utilizing inline definitions and quoted expressions for type-safe macro expansion.

modules/derivation/src/main · high confidence

The library has been restructured into a multi-module build, separating the GraphQL AST definitions (now in the \ast\ module) from the core execution logic (in the \core\ module). This change introduces a new \AstLocation\ model for precise source tracking, refactors the execution engine to use a pluggable \ExecutionScheme\ trait (supporting \Future\ and stream-based backends), and introduces an \AsyncValue\ type for \cats-effect\ integration. Users will see these components organized into distinct modules, with the core execution logic now relying on the separated AST definitions and a more modular resolver builder pattern.

repository · high confidence

The AST visitor implementation has been separated from the main query AST definitions into a new \AstVisitor\ component. This change introduces a dedicated visitor trait and command enumeration (\Skip\, \Continue\, \Break\) to handle traversal of GraphQL AST nodes, allowing for more modular and optimized processing of document structures without cluttering the core AST definitions.

modules/core/src/main/scala/sangria/ast · high confidence

A new \package.scala\ file has been added to the \modules/core/src/main/scala/sangria\ directory, establishing the root package object for the Sangria library. This file includes the primary library documentation and defines a private \since3\_0\_0\ constant, which serves as the version marker for deprecations introduced in version 3.0.0.

modules/core/src/main/scala/sangria · high confidence

Added the new @ApiMayChange annotation to mark APIs that are experimental and may evolve without strict source or binary compatibility guarantees. This allows developers to signal that specific methods, constructors, fields, types, or packages are in a transitional state and could change between patch releases, helping users understand the stability level of the features they are using.

modules/core/src/main/java · high confidence

The Long scalar type in the schema package now accepts string values as input, provided they can be successfully parsed as a valid Long integer. This change allows clients to pass Long values as strings, which is useful for avoiding precision loss in environments where large integers are transmitted as text.

modules/core/src/main/scala/sangria/schema · high confidence

The validation engine now enforces stricter GraphQL specification compliance by introducing several new validation rules. Most notably, the \ExactlyOneOfFieldGiven\ rule validates \oneOf\ input objects, ensuring that exactly one field is provided and non-null, which prevents ambiguous input data. Additional rules have been added to enforce document structure and correctness: \ExecutableDefinitions\ ensures only operations and fragments are present, \LoneAnonymousOperation\ restricts anonymous queries to single-operation documents, and \SingleFieldSubscriptions\ limits subscription operations to a single root field. The update also includes rules for variable and fragment integrity (\NoUndefinedVariables\, \NoUnusedVariables\, \NoUnusedFragments\, \NoFragmentCycles\), type safety (\KnownTypeNames\, \FieldsOnCorrectType\, \ValuesOfCorrectType\), and directive/argument uniqueness (\UniqueDirectivesPerLocation\, \UniqueArgumentNames\, \UniqueInputFieldNames\), providing comprehensive error reporting for malformed queries.

modules/core/src/main/scala/sangria/validation/rules · high confidence

This change introduces a new \Cache\ abstraction with two implementations—\ConcurrentHashMapCache\ for thread-safe access and \TrieMapCache\ for lock-free concurrency—allowing the library to manage cached data more efficiently. Additionally, \StringUtil\ now includes a custom \linesIterator\ for consistent cross-platform line splitting, an optimized \escapeString\ method, and a \suggestionList\ function for typo-tolerant input suggestions. The legacy \blockStringValue\ method is deprecated in favor of these updated utilities.

modules/core/src/main/scala/sangria/util · high confidence

The \OverlappingFieldsCanBeMerged\ validation rule now uses a new, high-performance implementation based on the Xing algorithm. This change introduces a dedicated internal AST representation (SelectionField, SelectionContainer) and a caching mechanism (CachedCheck) to significantly speed up the validation of field selection merging, while maintaining compatibility with the GraphQL specification.

modules/core/src/main/scala/sangria/validation/rules/overlappingfields · high confidence

The parser module has been restructured with new internal files (Lexical.scala, PositionTracking.scala) and sealed traits to improve visibility and maintainability. This change includes a fix for O(N^2) memory allocation when parsing newlines by using binary search for line index tracking, and a fix for array buffer handling in binary search. Additionally, the block string value processing is now handled via a dedicated Lexical object, and the package object deprecates the old SourceMapper type in favor of sangria.ast.SourceMapper.

modules/parser/src/main · high confidence

Added FS2-based test suite for GraphQL batch execution and subscriptions; Added benchmarks for query validation and string utilities; Added comprehensive GraphQL specification compliance tests; Added comprehensive test suite for Sangria derivation macros; Added parser test suite and resources; Added test coverage for cats-effect IO integration in Sangria; Added tests for Monix-based streaming subscriptions.

The build configuration has been completely restructured for the 4.0.0 release, moving from a single monolithic project to a multi-module architecture (ast, parser, core, derivation, etc.) and adding support for Scala 3 alongside Scala 2.12 and 2.13. Key dependencies have been updated, including parboiled to 2.5.1 and scalatest to 3.2.20, and binary compatibility checks (MiMa) are now enforced against the previous 4.0.0 artifacts with specific filters applied to accommodate breaking changes in the new module structure.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 39 → 61 (+22.6)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 82 (-18.4)
• Architecture 69 → 100 (+31.0)
• Maturity 43 → 53 (+9.9)
• Readiness 27 → 61 (+34.0)
• Security 38 → 65 (+27.7)

• Dimension evaluation failed
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• No artifact signing
• No automated tests
• No exposed public API
• No tests found
• Test reliability not included

• AstSchemaMaterializer.findOperationsTypes (cognitive 20) (modules/core/src/main/scala/sangria/schema/AstSchemaMaterializer.scala)
• AstSchemaMaterializer.findOperationsTypes (cyclomatic 17) (modules/core/src/main/scala/sangria/schema/AstSchemaMaterializer.scala)
• AstVisitor.visitAstRecursive (cognitive 94) (modules/core/src/main/scala/sangria/ast/AstVisitor.scala)
• AstVisitor.visitAstRecursive (cyclomatic 96) (modules/core/src/main/scala/sangria/ast/AstVisitor.scala)
• BatchExecutor.collectVariables (cognitive 19) (modules/core/src/main/scala/sangria/execution/batch/BatchExecutor.scala)
• BatchExecutor.findUsages (cyclomatic 16) (modules/core/src/main/scala/sangria/execution/batch/BatchExecutor.scala)
• ClassTooLong: DefaultAstSchemaBuilder (modules/core/src/main/scala/sangria/schema/AstSchemaBuilder.scala)
• DeriveEnumTypeMacro.collectEnumValues (cognitive 23) (modules/derivation/src/main/scala-2/sangria/macros/derive/DeriveEnumTypeMacro.scala)
• DeriveEnumTypeMacro.collectEnumValues (cognitive 24) (modules/derivation/src/main/scala-3/sangria/macros/derive/DeriveEnumTypeMacro.scala)
• DeriveEnumTypeMacro.collectKnownEnumSubtypes (cognitive 16) (modules/derivation/src/main/scala-2/sangria/macros/derive/DeriveEnumTypeMacro.scala)
• DeriveEnumTypeMacro.deriveEnumType (cognitive 22) (modules/derivation/src/main/scala-2/sangria/macros/derive/DeriveEnumTypeMacro.scala)
• DeriveEnumTypeMacro.deriveEnumType (cognitive 38) (modules/derivation/src/main/scala-3/sangria/macros/derive/DeriveEnumTypeMacro.scala)
• DeriveEnumTypeMacro.deriveEnumType (cyclomatic 20) (modules/derivation/src/main/scala-3/sangria/macros/derive/DeriveEnumTypeMacro.scala)
• DeriveInputObjectTypeMacro.collectFields (cognitive 31) (modules/derivation/src/main/scala-2/sangria/macros/derive/DeriveInputObjectTypeMacro.scala)
• DeriveInputObjectTypeMacro.collectFields (cognitive 76) (modules/derivation/src/main/scala-3/sangria/macros/derive/DeriveInputObjectTypeMacro.scala)
• DeriveInputObjectTypeMacro.collectFields (cyclomatic 25) (modules/derivation/src/main/scala-3/sangria/macros/derive/DeriveInputObjectTypeMacro.scala)
• DeriveObjectTypeMacro.collectFields (cognitive 31) (modules/derivation/src/main/scala-2/sangria/macros/derive/DeriveObjectTypeMacro.scala)
• DeriveObjectTypeMacro.collectFields (cognitive 41) (modules/derivation/src/main/scala-3/sangria/macros/derive/DeriveObjectTypeMacro.scala)
• DeriveObjectTypeMacro.collectFields (cyclomatic 21) (modules/derivation/src/main/scala-3/sangria/macros/derive/DeriveObjectTypeMacro.scala)
• DeriveObjectTypeMacro.createArg (cognitive 32) (modules/derivation/src/main/scala-3/sangria/macros/derive/DeriveObjectTypeMacro.scala)
• …and 151 more

• 26 commits — 26 feature/other, 0 fixes

• (repo) — 12 commits
• (root) — 5 commits
• modules/cats-effect-experimental — 3 commits
• project/plugins.sbt — 3 commits
• project/build.properties — 2 commits
• .github/workflows — 1 commit

• change: Merge pull request #1314 from scala-steward/update/scalafmt-core-3.11.5
• change: Merge pull request #1316 from scala-steward/update/sbt-1.12.15
• change: Merge pull request #1319 from scala-steward/update/classgraph-4.8.192
• change: Merge pull request #1320 from sangria-graphql/more_IO_tests
• change: Merge pull request #1323 from scala-steward/update/sbt-ci-release-1.12.1
• change: Merge pull request #1325 from scala-steward/update/sbt-1.13.0
• change: Merge pull request #1326 from scala-steward/update/classgraph-4.8.194
• change: Merge pull request #1327 from scala-steward/update/cats-effect-3.7.1
• change: Merge pull request #1328 from scala-steward/update/sbt-github-actions-0.32.0
• change: Merge pull request #1332 from scala-steward/update/fs2-core-3.14.0
• change: Merge pull request #1333 from scala-steward/update/sbt-github-actions-0.32.1
• change: Merge pull request #1335 from scala-steward/update/classgraph-4.8.195
• change: Regenerate GitHub Actions workflow
• change: Update cats-effect to 3.7.1
• change: Update classgraph to 4.8.192
• change: Update classgraph to 4.8.194
• change: Update classgraph to 4.8.195
• change: Update fs2-core to 3.14.0
• change: Update sbt, scripted-plugin to 1.12.15
• change: Update sbt, scripted-plugin to 1.13.0
• …and 6 more

• Containers 0 added · 0 removed · contexts 1 added · 0 removed · edges 0 added · 0 removed

• repository

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

sangria-graphql/sangria was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.