Mill plugin for guardrail generation

import $ivy.`io.github.jackcviers::mill-guardrail::<release-version>`
import io.github.jackcviers.mill.guardrail._


object MyModule extends Guardrail{

  override def ivyDeps = T.task{
    super.ivyDeps() ++ Agg(
	  // specific dedendencies for the framework and guardrail extensions you choose to use.
	)
  }
}

By default, this will generate scala code for the server, client, and model dto files in the guardrail spec files using the defualt guardrail args for scala and use the http4s framework without tracing, custom extraction, or auth and with empty modules ignoring tags. You can override this task and set your own framework and dev.Guardrail.Args for each spec file, including the contextual arguments for dev.guardrail.Context, which controls tracing, custom extraction, module loading, tag behaviors, and auth implementations during module compilation. See the Guardrail documentation for all the possible configuration options, and tests in the itest module for some demonstrations.

Guardrail only outputs scala 2.13 sources at the moment. You may consider separating your generated sources in their own modules and depending upon them for Scala 3 modules, as Scala 3 can use 2.13 dependencies.

mill-guardrail is compatible with mill 0.11.x+.

By default, mill-guardrail will look in <modulePath>/guardrail/ for specification json/yml/yaml files. You may customize this by overriding Guardrail#guardrailDirectories in your module definition.

By default, mill-guardrail will identify all json, yaml, and yml files in the Guardrail#guardrailDirectories and their children. You can override this behavior by overriding Guardrail#guardrailSpecFiles in your module definition. Commonly, you may want to filter out a specific spec file. See the example below:

object MyModule extends Guardrail{

  override def guardrailSpecFiles = T.sources {
    super
      .guardrailSpecFiles()
	  .filter{ pathRef => 
	    !pathRef.path.lastOption.exists(_.contains("specFileToFilter"))
	  }
  }
}

You can choose the framework, language for code generation, and the other guardrail-specific settings by overriding Guardrail#guardrailTasks in your module. Typically, you may want to filter out the client, server, or model generation for the specifications. The tasks are returned in an Agg[Guardrail.LanguageAndArgs]. An example removing server generation from the default arguments is below:

import dev.{guardrail => dg}

// ...

object MyModule extends Guardrail{

  override def guardrailTasks: define.Task[Agg[Guardrail.LanguageAndArgs]] = T.task{
    super.guardrailTasks().map{ (languageAndArgs: Guardrail.LanguageAndArgs) =>
	  languageAndArgs.copy(args = languageAndArgs.args.filterNot{ a: (dg.Args) =>
	    a.kind == CodegenTarget.Server
	  })
	}
  }
}

See the itest test modules build.sc and the Guardrail documentation for more information on how to customize the language, framework, and Guardrail extension and module definitions.

• Scala Default (Http4s Client/Server/Models/Circe)
• Scala Default No Server (Http4s/Circe)
• Scala akka-http
• Scala akka-http-jackson

Java code generation does not work, pending an answer to guardrail/issues/1953.

All code contributed to this repository MUST include the generated license header, generated using https://index.scala-lang.org/lewisjkl/header. The build for PRs will run ./mill __.headerCheck and fail if these headers are not created.

You can add the headers to any files you add with ./mill __.headerCreate before comitting.

millguardrail contains the plug-in source files. The project is set up for mill cross-building. Inside millguardrail, src-0.11 contains the mill 0.11.x-specific files. Contributions extending the plug-in to earlier versions of mill are greatly appreciated.

itest contains the plug-in tests themselves. Issue pull-requests are welcome with only a test in itest to assist with replication.

This plug-in was heavily influenced by sbt-guardrail, though it is not quite a 1:1 port.

The build structure was heavily influenced by mill-vcs-version.