guardrail-dev/guardrail

Guardrail is a code generation tool that produces client and server implementations for Java and Scala applications from OpenAPI specifications. It supports multiple web frameworks, including Akka HTTP, http4s, Spring MVC, and Dropwizard, allowing developers to generate type-safe HTTP handlers and API clients. The system handles serialization via Jackson and Circe, manages authentication strategies, and ensures compatibility with various collection libraries like Vavr.

25 changes.

The project underwent a major architectural restructure, migrating to a modular layout with Nix-based development environments and upgrading the sbt build infrastructure. This period focused heavily on expanding test coverage across all generator modules, particularly for Akka HTTP, http4s, and Dropwizard, to ensure correctness of code generation and integration behaviors.

44 changes.

The project expanded its code generation capabilities by introducing new modules for Java (Spring MVC, Dropwizard, AsyncHttpClient) and Scala (Akka HTTP, http4s, Dropwizard). This period focused on implementing framework-specific generators, adding support for libraries like Vavr and Jackson, and restructuring the core engine to support OpenAPI 3.1 and improved error handling. Comprehensive test suites were added to validate the generated code across all new frameworks and samples.

7 changes.

This period focused on expanding test coverage for the Java and Scala code generators, including validation of collection abstractions, recursive schemas, and CLI argument parsing. It also introduced Java generator SPI registrations to enable runtime discovery of language-specific implementations and added validation tests for Circe-refined decoding in the Akka HTTP sample module.

A new PositiveLong value class is introduced to represent non-negative long integers, enforcing validation via javax.validation constraints (Min(0), NotNull). This type includes custom Jackson deserialization logic using @JsonCreator annotations to handle both numeric and string inputs, ensuring that invalid values throw an IllegalArgumentException. Implicit encoders, decoders, and validators are provided for both client and server sides of the Akka HTTP Jackson integration, enabling seamless serialization and validation of this type in API payloads.

modules/sample-akkaHttpJackson/src/main · high confidence

New \PositiveLong\ value types have been added to the support packages of both the Akka HTTP and http4s sample modules. These types enforce that long values are non-negative and provide automatic JSON decoding and string representation via circe, ensuring that invalid negative values are rejected during deserialization with a clear error message.

modules/sample-akkaHttp/src/main, modules/sample-http4s/src/main · high confidence

A new PositiveLong value class has been introduced in the sample-http4s-v0\_22 module to represent non-negative long values. This type includes a decoder that validates input is non-negative and fails with a descriptive error message otherwise, along with a showable instance for string representation, enabling safer handling of positive long values in HTTP4s-based examples.

_modules/sample-http4s-v0\22/src/main · high confidence

The Java code generator now supports mapping Scala collections to Vavr equivalents, specifically generating code for \io.vavr.control.Option\, \io.vavr.collection.Vector\/\List\/\Seq\, and \io.vavr.concurrent.Future\. This change introduces helper utilities in \JavaCollectionsHelpers\ and implements the \CollectionsAbstraction\ trait in \JavaVavrCollections\ to handle lifting types, mapping, filtering, and converting between Vavr types and Java standard library types like \CompletionStage\.

modules/java-support/src/main/scala/dev/guardrail/terms · high confidence

This change introduces the Java Dropwizard server generator, enabling the generation of server-side code for the Dropwizard framework. It includes the core generator classes (DropwizardGenerator and DropwizardServerGenerator) and registers them via Java SPI service files (FrameworkGeneratorLoader and ServerGeneratorLoader). The generator supports standard HTTP status code mappings, content types, and basic authentication structures for Java-based Dropwizard applications.

modules/java-dropwizard/src/main · high confidence

Guardrail now includes a new Java Spring MVC generator module, enabling users to generate Spring MVC server-side code (controllers, handlers, and routing) from OpenAPI specifications. The module registers itself via Java SPI loaders and implements the server generator terms, including HTTP status code mapping and content-type handling. Client generation is currently stubbed out with a user error, indicating that server-side generation is the primary initial capability.

modules/java-spring-mvc · high confidence

This change introduces the first iteration of the Scala Dropwizard generator, enabling users to generate server-side code for the Dropwizard framework. The implementation registers new SPI loaders for the client, server, and framework generators, allowing the tool to recognize 'dropwizard' as a valid target. The server generator provides route handling, HTTP status code mapping, and support for various content types and security schemes, while the client generator is currently a stub that raises an error indicating that client generation is not yet supported.

modules/scala-dropwizard · high confidence

This change adds the core implementation for generating Scala http4s clients, servers, and framework integrations. It registers the new generators via SPI service files (ClientGeneratorLoader, ServerGeneratorLoader, FrameworkGeneratorLoader) and provides the Http4sClientGenerator, Http4sServerGenerator, and Http4sGenerator classes. The client generator now supports tracing, handles multipart form data, and includes logic for URL parameter formatting. The framework generator provides necessary imports, implicits (like path escaping and entity encoding/decoding), and HTTP status code lookups. A new Http4sPathExtractor handles path segment extraction for route matching.

modules/scala-http4s/src/main · high confidence

A new \ResponseHelpers\ object has been added to the Java support module, providing logic to determine the best matching content type for request consumes and response produces based on priority lists and fallback rules. It also includes utility functions for parsing and finding common prefixes in route paths. This change introduces a new helper component for the Java generator without altering existing public APIs.

modules/java-support/src/main/scala/dev/guardrail/java · high confidence

The Java generator now includes a dedicated Jackson helper module that implements the \discriminatorExpression\ function. This addition enables the generator to correctly produce Jackson discriminator annotations for polymorphic types by mapping specific raw types (such as strings, booleans, integers, and numbers with formats like int32/int64/float/double) to their corresponding Java literal nodes, while raising user errors for unsupported discriminator formats.

modules/java-support/src/main/scala/dev/guardrail/generators/java/jackson · high confidence

New META-INF/services files register the Java-specific implementations for the generator SPI, including JavaCollectionsGeneratorLoader (supporting Vavr and standard collections), CoreTermsLoader, FrameworkLoader, LanguageLoader, ModuleMapperLoader, and JacksonProtocolGeneratorLoader. This enables the framework to discover and use these Java generators at runtime.

modules/java-support/src/main/resources · high confidence

This change introduces the Akka HTTP code generator for the Scala guardrail module. It registers the generator via Java SPI service files (ClientGeneratorLoader, FrameworkGeneratorLoader, ServerGeneratorLoader) and implements the core generation logic in AkkaHttpClientGenerator, AkkaHttpGenerator, and supporting helpers. The generator supports Circe and Jackson model types, handles path extraction and parameter binding for Akka HTTP routes, and provides marshalling/unmarshalling implicits for JSON and text/plain content types.

modules/scala-akka-http/src/main · high confidence

The java-async-http module now provides a dedicated client generator for the AsyncHttpClient library. This change introduces the AsyncHttpClientClientGenerator and its loader, enabling the generation of Java client code that utilizes AsyncHttpClient for HTTP operations. The generator is registered via the standard SPI mechanism and includes helper utilities for handling response parsing and configuration specific to the AsyncHttpClient framework.

modules/java-async-http · high confidence

This change introduces several new shell scripts in the \support/\ directory to automate and improve the CI workflow. \current-pr-labels.sh\ uses the GitHub Search API to discover and cache labels for the current PR, ensuring accurate labeling even on master builds. \label-scala-steward-prs.sh\ automatically tags Scala Steward PRs with the 'chore' label. \trigger-all-releases.sh\ orchestrates the promotion of draft releases in dependency order, waiting for POM availability before proceeding. \rebase-formatting.sh\ provides a robust tool for distributing formatting changes across a branch to minimize merge conflicts. Additionally, \generate-sidebars.sh\ automates the creation of documentation sidebars for the new docsify-based site, and \write-pathological.sh\ generates a test case for issue \#45.

support · high confidence

Users can now use the --auth-implementation CLI flag to explicitly select how authentication is handled in generated code. The supported options are 'disable' (no auth), 'native' (framework-native auth), 'simple' (basic auth), and 'custom' (user-provided logic). This allows for finer control over the generated authentication middleware and security requirements.

repository · high confidence

The Java code generator has been restructured to use a new SPI-based loader system, introducing dedicated loaders for the language, core terms, collections, and frameworks. This change adds support for generating code using the Java Standard Library collections (java-stdlib) and the Vavr library (java-vavr) via separate generators. It also introduces a module mapper that automatically resolves required dependencies for Dropwizard and Spring MVC frameworks, ensuring the correct libraries (such as Jackson and async-http-client) are included in the generated output.

modules/java-support/src/main/scala/dev/guardrail/generators/java · high confidence

Added a new \Java.scala\ syntax module in the Java support generator that provides implicit classes for manipulating JavaParser types (such as boxing/unboxing primitives and checking type names) and utility functions for safely parsing Java code snippets into AST nodes. This includes helpers for generating method calls, handling null checks, and formatting parse errors, enabling more robust Java code generation within the guardrail framework.

modules/java-support/src/main/scala/dev/guardrail/generators/java/syntax · high confidence

The Scala support module now registers its core components via Java SPI (META-INF/services), including loaders for the language, framework, collections, core terms, module mapping, and protocol generators (Circe, Circe-Refined, and Jackson). This enables the framework to discover and instantiate Scala-specific code generation logic, such as the new ScalaCollectionsGenerator for standard collection types, the ScalaGenerator for general language terms, and the Circe/Circe-Refined/Jackson protocol generators for serialization, while also introducing validation support in the Circe-Refined generator for array sizes, string patterns, and integer ranges.

modules/scala-support/src/main · high confidence

The project's build configuration has been restructured from a monolithic definition into a set of distinct SBT modules (core, cli, scalaAkkaHttp, scalaHttp4s, javaSpringMvc, javaDropwizard, etc.). This modularization centralizes dependency management for each target framework, introducing updated versions such as Cats 2.10.0, http4s 0.23.24, and Spring Boot 2.7.18. The core module now generates Args and Context POJOs dynamically, and the build supports multiple sample projects per framework to validate the generated code against specific library versions.

project/src/main/scala/modules · high confidence

The project has been reorganized into a modular structure with dedicated directories for Scala (akka-http, http4s) and Java (Dropwizard, Spring MVC) generators, alongside a new CLI module. To streamline local development, the repository now includes Nix flakes (flake.nix, flake.lock) and a shell.nix for reproducible environments, along with configuration files for scalafmt 3.11.3, Scala Steward, and JVM options. Documentation has been consolidated and updated, including a new compatibility matrix, migration guides for recent breaking changes, and updated contributing guidelines.

(repo-wide) · high confidence

The sample Dropwizard and Spring MVC applications now include a shared PositiveLong support class in the examples.support package. This class enables JSON serialization and deserialization of positive long values, ensuring that negative values are rejected during parsing with an IllegalArgumentException.

modules/sample-dropwizard/src/main, modules/sample-springMvc/src/main · high confidence

The main CLI entry point has been refactored to extend the new CLICommon trait, centralizing argument processing logic. This change moves the core parsing and execution flow into a shared base class, making the CLI implementation more modular and testable while maintaining the same command-line interface behavior.

modules/cli/src/main · medium confidence

The core code generation engine has been restructured to improve error reporting, type safety, and compatibility with OpenAPI 3.1. A new \Target\ effect type replaces previous error-handling patterns, providing stricter monadic error propagation and integrated structured logging for better debugging. The \Tracker\ system now maintains a human-readable history of property access paths, which is automatically appended to error messages when fields are missing or invalid. Additionally, the engine now supports OpenAPI 3.1 by handling \JsonSchema\ alongside \ObjectSchema\ and introduces \IndexedFunctor\/\IndexedDistributive\ abstractions for safer traversal of nested structures. Scala 2.12-specific collection shims (e.g., \distinctBy\, \groupMap\) have been added to maintain compatibility, while Scala 2.13 uses native implementations.

modules/core/src/main · high confidence

The build configuration has been reorganized into modular Scala files (Build.scala, Dependencies.scala, etc.) and upgraded to support Scala 2.12.18 and 2.13.18, with test dependencies updated to ScalaTest 3.2.20 and ScalaCheck 1.19.0. The project now targets Java 17 bytecode and includes support for http4s 0.23.6 alongside existing http4s 0.22.x versions. Binary compatibility checks are now conditionally enforced based on CI environment variables and PR labels, and the package organization has been repackaged from com.twilio.guardrail to dev.guardrail.

project/src/main/scala · high confidence

The build system has been upgraded to sbt 1.12.13, bringing significant changes to the development and release experience. This update introduces a new welcome message that highlights key sbt tasks such as \cli\, \format\, and \runExample\, and adds a \runIssue\ command for targeted code generation. The release pipeline is now handled by \sbt-ci-release\ 1.12.0 and \sbt-github-release\ 0.7.0, replacing previous mechanisms. Code quality and formatting are enforced via \sbt-wartremover\ 3.6.1, \sbt-scalafmt\ 2.6.1, and \sbt-scalafix\ 0.14.7, while documentation is generated using \sbt-mdoc\ 2.5.4. Additionally, the project now uses \sbt-version-policy\ 3.3.0 to ensure binary compatibility and \sbt-scoverage\ 2.4.4 for code coverage, with a new interop module providing utilities for generating POJOs and managing Scala meta ASTs.

project · high confidence

Added Akka HTTP integration tests; Added EitherT test utilities for sample projects; Added Scala test coverage for Circe-refined validation and large object generation; Added ScalaMeta syntax matching support for tests; Added ScalaMeta test matchers for structure and equality; Added Swagger spec test runner support; Added authentication tests for the http4s sample module; Added core and generator test suites for Scala code generation; Added empty test application class; Added http4s integration tests for specific issue scenarios; Added integration and unit tests for the Dropwizard server sample; Added integration tests for Akka HTTP Jackson sample; Added integration tests for Spring MVC alias and DateTime handlers; Added integration tests for http4s sample project; Added integration tests for the Spring MVC pet store sample; Added integration tests for the http4s 0.22 sample module; Added parameter escaping tests for Akka HTTP and http4s samples; Added round-trip tests for custom headers and form data in http4s; Added test configuration for Spring MVC sample; Added test coverage for Akka HTTP server and client behaviors; Added test coverage for Dropwizard Java code generation; Added test coverage for Dropwizard client and server components; Added test coverage for Jackson code generation features; Added test coverage for Java code generation and module loading; Added test coverage for custom header round-tripping in Akka HTTP; Added test coverage for http4s client and server code generation; Added test coverage for the Akka-HTTP Jackson sample module; Added test helper for Tracker instantiation; Added test helpers for Dropwizard integration testing; Added test utilities for validating EitherT results; Added tests for Akka HTTP Jackson custom header round-tripping; Added tests for Akka HTTP text/plain client support; Added tests for Akka-HTTP Jackson client with text/plain content type; Added tests for CLI argument parsing and validation; Added tests for Circe JSON nullability handling; Added tests for Circe redaction behavior; Added tests for Jackson discriminator expression generation; Added tests for Java client/server class naming in Dropwizard generator; Added tests for ModuleLoadResult component consumption and error reporting; Added tests for Scala code generation and structured logging; Added tests for Scala code generation package structure; Added tests for Swagger vendor extension extraction; Added tests for fully qualified name generation in http4s clients; Added tests for http4s client default parameter generation; Added tests for http4s text/plain content type handling; Added unit tests for Jackson discriminator expression generation; Added validation tests for Circe-refined decoding; Enable Dropwizard-Vavr sample with comprehensive test coverage; Expanded test coverage for Akka HTTP code generation; Initial Dropwizard Scala server sample with comprehensive test coverage.

The project now includes the docsify-cli npm package (version ^4.4.4) as a dependency to support the generation and serving of the documentation microsite. This addition is reflected in the new package.json and package-lock.json files, enabling the build system to compile and preview the documentation site.

(dependencies) · high confidence

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

• First survey — no prior run to compare against. CAI 62.

• Code Health 72
• Architecture 97
• Maturity 53
• Readiness 62
• Security 75

• 300 commits — 296 feature/other, 4 fixes

• (repo) — 94 commits
• project/src — 37 commits
• .github/workflows — 35 commits
• modules/scala-support — 32 commits
• modules/core — 22 commits
• (root) — 18 commits
• modules/microsite — 8 commits
• support/current-pr-labels.sh — 7 commits
• modules/sample — 5 commits
• modules/cli — 4 commits
• src/test — 4 commits
• docs/plugins — 3 commits
• project/version-policy.sbt — 3 commits
• project/wartremover.sbt — 3 commits
• .github/dependabot.yml — 2 commits
• modules/java-support — 2 commits
• modules/scala-akka-http — 2 commits
• project/build.properties — 2 commits
• project/ci-release.sbt — 2 commits
• project/scalafmt.sbt — 2 commits

• fix: Fix JavaParser parent links in Java generators
• fix: Fix parser warning for #264
• fix: Merge pull request #1902 from blast-hardcheese/fix-ci
• fix: Merge pull request #2279 from guardrail-dev/fix/javaparser-parent-links
• change: -z $msg is apparently a thing
• change: Add 'Reformat with scalafmt 3.11.1' to .git-blame-ignore-revs
• change: Add GITHUB_TOKEN to release
• change: Add TODO
• change: Add dispatch args for release action
• change: Add new GA4 token
• change: Add required "distribution" parameter to setup-java
• change: Add scala types test with 3.0.0 OpenAPI spec
• change: Add scala types test with 3.1.0 OpenAPI spec
• change: Adding a note about upcoming ABI changes
• change: Adding a test case for #1642
• change: Adding direnv
• change: Adding issue195 test case
• change: Adding runIssue to welcome message
• change: Addressing new ObjectSchema vs JsonSchema considerations in OAI 3.1
• change: Addressing unintentional URL creation
• …and 280 more

• 0 containers · 1 bounded contexts · 0 dependency edges (baseline)

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

guardrail-dev/guardrail 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.