From c5a1f0bb61601f0154b0d50f0ab061cca76a7e84 Mon Sep 17 00:00:00 2001 From: tudor-da Date: Wed, 10 Nov 2021 19:08:33 +0100 Subject: [PATCH] Republish error codes generator lib (#11633) * Republish error codes generator libraries * Additionally, add kvutils to classpath for generating KVErrors docs CHANGELOG_BEGIN CHANGELOG_END * Use a new annotation (DeprecatedDocs) instead of @deprecated * Needed for adding descriptions to the error groups docs. Needed for allowing cross-compilation to 2.12 and 2.13, not possible due to the reflections machinery of extracting the message from @deprecated --- ledger/error/generator/BUILD.bazel | 25 +++++++++++++++-- .../com/daml/error/generator/app}/Main.scala | 3 +- .../ErrorCodeDocumentationGenerator.scala | 28 ++++++++----------- .../daml/error/generator/ErrorDocItem.scala | 0 .../daml/error/generator/GroupDocItem.scala | 0 .../ErrorCodeDocumentationGeneratorSpec.scala | 0 .../main/scala/com/daml/error/ErrorCode.scala | 1 + .../state/kvutils/errors/KVErrors.scala | 13 +++++++++ release/artifacts.yaml | 2 ++ 9 files changed, 52 insertions(+), 20 deletions(-) rename ledger/error/generator/{src/main/scala/com/daml/error/generator => app/src/main/scala/com/daml/error/generator/app}/Main.scala (93%) rename ledger/error/generator/{ => lib}/src/main/scala/com/daml/error/generator/ErrorCodeDocumentationGenerator.scala (90%) rename ledger/error/generator/{ => lib}/src/main/scala/com/daml/error/generator/ErrorDocItem.scala (100%) rename ledger/error/generator/{ => lib}/src/main/scala/com/daml/error/generator/GroupDocItem.scala (100%) rename ledger/error/generator/{src/test/suite => lib/src/test}/scala/com/daml/error/generator/ErrorCodeDocumentationGeneratorSpec.scala (100%) diff --git a/ledger/error/generator/BUILD.bazel b/ledger/error/generator/BUILD.bazel index e5a621154f0e..14b534483e6c 100644 --- a/ledger/error/generator/BUILD.bazel +++ b/ledger/error/generator/BUILD.bazel @@ -4,25 +4,44 @@ load( "//bazel_tools:scala.bzl", "da_scala_binary", + "da_scala_library", "da_scala_test_suite", ) load("@scala_version//:index.bzl", "scala_major_version") da_scala_binary( name = "export-error-codes-json-app", - srcs = glob(["src/main/scala/**/*.scala"]), - main_class = "com.daml.error.generator.Main", + srcs = glob(["app/src/main/scala/**/*.scala"]), + main_class = "com.daml.error.generator.app.Main", resources = glob(["src/main/resources/**/*"]), scala_deps = [ "@maven//:io_circe_circe_core", "@maven//:org_typelevel_cats_core", ], visibility = ["//visibility:public"], + runtime_deps = [ + # Add the KVErrors to the classpath so they can be picked up by the generator + "//ledger/participant-state/kvutils", + ], + deps = [ + "//ledger/error", + "//ledger/error/generator:lib", + ], +) + +da_scala_library( + name = "lib", + srcs = glob(["lib/src/main/scala/**/*.scala"]), + tags = ["maven_coordinates=com.daml:error-generator-lib:__VERSION__"], + versioned_scala_deps = { + "2.12": ["@maven//:org_scala_lang_modules_scala_collection_compat"], + }, + visibility = ["//visibility:public"], deps = [ "//ledger/error", "@maven//:org_reflections_reflections", ], -) if scala_major_version == "2.13" else None +) da_scala_test_suite( name = "export-error-codes-json-tests", diff --git a/ledger/error/generator/src/main/scala/com/daml/error/generator/Main.scala b/ledger/error/generator/app/src/main/scala/com/daml/error/generator/app/Main.scala similarity index 93% rename from ledger/error/generator/src/main/scala/com/daml/error/generator/Main.scala rename to ledger/error/generator/app/src/main/scala/com/daml/error/generator/app/Main.scala index 3455419c0629..9123f1617190 100644 --- a/ledger/error/generator/src/main/scala/com/daml/error/generator/Main.scala +++ b/ledger/error/generator/app/src/main/scala/com/daml/error/generator/app/Main.scala @@ -1,9 +1,10 @@ // Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. // SPDX-License-Identifier: Apache-2.0 -package com.daml.error.generator +package com.daml.error.generator.app import com.daml.error.Grouping +import com.daml.error.generator.{ErrorCodeDocumentationGenerator, ErrorDocItem, GroupDocItem} import io.circe.Encoder import io.circe.syntax._ diff --git a/ledger/error/generator/src/main/scala/com/daml/error/generator/ErrorCodeDocumentationGenerator.scala b/ledger/error/generator/lib/src/main/scala/com/daml/error/generator/ErrorCodeDocumentationGenerator.scala similarity index 90% rename from ledger/error/generator/src/main/scala/com/daml/error/generator/ErrorCodeDocumentationGenerator.scala rename to ledger/error/generator/lib/src/main/scala/com/daml/error/generator/ErrorCodeDocumentationGenerator.scala index 1af549e1328d..ac286b4c724f 100644 --- a/ledger/error/generator/src/main/scala/com/daml/error/generator/ErrorCodeDocumentationGenerator.scala +++ b/ledger/error/generator/lib/src/main/scala/com/daml/error/generator/ErrorCodeDocumentationGenerator.scala @@ -4,10 +4,10 @@ package com.daml.error.generator import java.lang.reflect.Modifier - -import com.daml.error.{Deprecation, ErrorCode, ErrorGroup, Explanation, Resolution} +import com.daml.error.{DeprecatedDocs, Deprecation, ErrorCode, ErrorGroup, Explanation, Resolution} import com.daml.error.generator.ErrorCodeDocumentationGenerator.{ acceptedTypeNames, + deprecatedDocsTypeName, deprecatedTypeName, explanationTypeName, resolutionTypeName, @@ -163,13 +163,17 @@ class ErrorCodeDocumentationGenerator(prefixes: Array[String] = Array("com.daml" val doc = annotations.foldLeft(GetAnnotationsState(None, None, None)) { case (state, annotation) => - if (isAnnotation(annotation, deprecatedTypeName)) - update(state, updatedDeprecation = Some(parseDeprecatedAnnotationValue(annotation.tree))) + if (isAnnotation(annotation, deprecatedDocsTypeName)) + update(state, updatedDeprecation = Some(parseAnnotationValue(annotation.tree))) else if (isAnnotation(annotation, explanationTypeName)) update(state, updatedExplanation = Some(parseAnnotationValue(annotation.tree))) else if (isAnnotation(annotation, resolutionTypeName)) update(state, updatedResolution = Some(parseAnnotationValue(annotation.tree))) - else + else if (isAnnotation(annotation, deprecatedTypeName)) { + // Ignore @deprecate annotations + // TODO Scala 2.13: Use these annotations to extract the docs description instead of the redundant [[DeprecatedDocs]] + state + } else sys.error( s"Unexpected annotation detected (${annotations.map(annotationTypeName)} but the only supported ones are $acceptedTypeNames)." ) @@ -178,16 +182,6 @@ class ErrorCodeDocumentationGenerator(prefixes: Array[String] = Array("com.daml" ErrorDocumentationAnnotations(doc.deprecation, doc.explanation, doc.resolution) } - private def parseDeprecatedAnnotationValue(tree: ru.Tree): String = - tree - .children(1) - .asInstanceOf[ru.NamedArg] - .children(1) - .asInstanceOf[ru.Literal] - .value - .value - .asInstanceOf[String] - @SuppressWarnings(Array("org.wartremover.warts.AsInstanceOf")) private def parseAnnotationValue(tree: ru.Tree): String = { try { @@ -216,8 +210,10 @@ private object ErrorCodeDocumentationGenerator { private val runtimeMirror: ru.Mirror = ru.runtimeMirror(getClass.getClassLoader) private val deprecatedTypeName = classOf[deprecated].getTypeName.replace("scala.", "") + private val deprecatedDocsTypeName = classOf[DeprecatedDocs].getTypeName.replace("$", ".") private val explanationTypeName = classOf[Explanation].getTypeName.replace("$", ".") private val resolutionTypeName = classOf[Resolution].getTypeName.replace("$", ".") - private val acceptedTypeNames = Set(deprecatedTypeName, explanationTypeName, resolutionTypeName) + private val acceptedTypeNames = + Set(deprecatedTypeName, deprecatedDocsTypeName, explanationTypeName, resolutionTypeName) } diff --git a/ledger/error/generator/src/main/scala/com/daml/error/generator/ErrorDocItem.scala b/ledger/error/generator/lib/src/main/scala/com/daml/error/generator/ErrorDocItem.scala similarity index 100% rename from ledger/error/generator/src/main/scala/com/daml/error/generator/ErrorDocItem.scala rename to ledger/error/generator/lib/src/main/scala/com/daml/error/generator/ErrorDocItem.scala diff --git a/ledger/error/generator/src/main/scala/com/daml/error/generator/GroupDocItem.scala b/ledger/error/generator/lib/src/main/scala/com/daml/error/generator/GroupDocItem.scala similarity index 100% rename from ledger/error/generator/src/main/scala/com/daml/error/generator/GroupDocItem.scala rename to ledger/error/generator/lib/src/main/scala/com/daml/error/generator/GroupDocItem.scala diff --git a/ledger/error/generator/src/test/suite/scala/com/daml/error/generator/ErrorCodeDocumentationGeneratorSpec.scala b/ledger/error/generator/lib/src/test/scala/com/daml/error/generator/ErrorCodeDocumentationGeneratorSpec.scala similarity index 100% rename from ledger/error/generator/src/test/suite/scala/com/daml/error/generator/ErrorCodeDocumentationGeneratorSpec.scala rename to ledger/error/generator/lib/src/test/scala/com/daml/error/generator/ErrorCodeDocumentationGeneratorSpec.scala diff --git a/ledger/error/src/main/scala/com/daml/error/ErrorCode.scala b/ledger/error/src/main/scala/com/daml/error/ErrorCode.scala index 2e5a72d3ba07..df5251bd46a0 100644 --- a/ledger/error/src/main/scala/com/daml/error/ErrorCode.scala +++ b/ledger/error/src/main/scala/com/daml/error/ErrorCode.scala @@ -264,3 +264,4 @@ object ErrorCode { case class Deprecation(deprecation: String) extends StaticAnnotation case class Explanation(explanation: String) extends StaticAnnotation case class Resolution(resolution: String) extends StaticAnnotation +case class DeprecatedDocs(description: String) extends StaticAnnotation diff --git a/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/errors/KVErrors.scala b/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/errors/KVErrors.scala index ea97255050f0..9bd8ed58ccf1 100644 --- a/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/errors/KVErrors.scala +++ b/ledger/participant-state/kvutils/src/main/scala/com/daml/ledger/participant/state/kvutils/errors/KVErrors.scala @@ -6,6 +6,7 @@ package com.daml.ledger.participant.state.kvutils.errors import java.time.Instant import com.daml.error.{ ContextualizedErrorLogger, + DeprecatedDocs, ErrorCategory, ErrorCode, ErrorGroup, @@ -374,6 +375,9 @@ object KVErrors extends LedgerApiErrorGroup { "The ledger time of the submission violated some constraint on the ledger time." ) @Resolution("Retry the transaction submission.") + @DeprecatedDocs( + "It was produced by submissions batching and it's not produced anymore by pre-execution." + ) @deprecated( "It was produced by submissions batching and it's not produced anymore by pre-execution." ) @@ -400,6 +404,9 @@ object KVErrors extends LedgerApiErrorGroup { "Check that all the informee party identifiers are correct, allocate all the informee parties, " + "request their allocation or wait for them to be allocated before retrying the transactiomn submission." ) + @DeprecatedDocs( + "Corresponds to transaction submission rejections that are not produced anymore." + ) @deprecated("Corresponds to transaction submission rejections that are not produced anymore.") object PartyNotKnownOnLedger extends ErrorCode( @@ -422,6 +429,9 @@ object KVErrors extends LedgerApiErrorGroup { @Explanation("An invalid transaction submission was not detected by the participant.") @Resolution("Contact support.") + @DeprecatedDocs( + "Corresponds to transaction submission rejections that are not produced anymore." + ) @deprecated("Corresponds to transaction submission rejections that are not produced anymore.") object Disputed extends ErrorCode( @@ -444,6 +454,9 @@ object KVErrors extends LedgerApiErrorGroup { "without an archived contract as an input, or the transaction submission may be retried " + "to load the up-to-date value of a contract key." ) + @DeprecatedDocs( + "Corresponds to transaction submission rejections that are not produced anymore." + ) @deprecated("Corresponds to transaction submission rejections that are not produced anymore.") object Inconsistent extends ErrorCode( diff --git a/release/artifacts.yaml b/release/artifacts.yaml index 934a9925b8cd..eb0ed704164d 100644 --- a/release/artifacts.yaml +++ b/release/artifacts.yaml @@ -237,3 +237,5 @@ type: jar-scala - target: //ledger/error:error type: jar-scala +- target: //ledger/error/generator:lib + type: jar-scala