|
| 1 | +/** |
| 2 | + * This is a Gradle script for proto linting. |
| 3 | + * |
| 4 | + * Implementation: |
| 5 | + * 1. Integrates the 'buf' CLI tool to compile .proto files and generate a JSON AST (Abstract Syntax Tree) image. |
| 6 | + * 2. Uses Groovy's JsonSlurper to parse the AST image. |
| 7 | + * 3. Traverses all Enum definitions and validates them against preset rules. |
| 8 | + * |
| 9 | + * Current Validation: |
| 10 | + * Enforces the java-tron API evolution standard (see https://github.com/tronprotocol/java-tron/issues/6515). |
| 11 | + * Except for legacy enums in the 'legacyEnums' whitelist, all newly defined Enums MUST reserve index 0 for a field starting with 'UNKNOWN_'. |
| 12 | + * This ensures robust forward/backward compatibility during proto3 JSON serialization. |
| 13 | + */ |
| 14 | +import groovy.json.JsonBuilder |
| 15 | +import groovy.json.JsonSlurper |
| 16 | +import org.gradle.internal.os.OperatingSystem |
| 17 | + |
| 18 | +// Define the required buf CLI version |
| 19 | +def bufVersion = "1.61.0" |
| 20 | +def currentOs = OperatingSystem.current() |
| 21 | +def platform = currentOs.isMacOsX() ? "osx" : (currentOs.isWindows() ? "windows" : "linux") |
| 22 | +def machine = rootProject.archInfo.isArm64 ? "aarch_64" : "x86_64" |
| 23 | + |
| 24 | +// Create a custom configuration for the buf CLI tool to keep it isolated from the classpath |
| 25 | +configurations { |
| 26 | + bufTool |
| 27 | +} |
| 28 | + |
| 29 | +// Depend on the buf executable published on Maven Central |
| 30 | +dependencies { |
| 31 | + bufTool "build.buf:buf:${bufVersion}:${platform}-${machine}@exe" |
| 32 | +} |
| 33 | + |
| 34 | +task protoLint { |
| 35 | + group = "verification" |
| 36 | + description = "Validate Protobuf Enums using buf generated JSON AST. Enforces 'UNKNOWN_' prefix for index 0 to ensure JSON serialization backward compatibility." |
| 37 | + |
| 38 | + // Explicitly depend on: |
| 39 | + // 1. extractIncludeProto: ensure external protos are extracted before buf runs. |
| 40 | + // The include root is derived from that task's actual output below. |
| 41 | + // 2. generateProto: fix Gradle implicit dependency warning due to output directory overlap. |
| 42 | + dependsOn 'extractIncludeProto', 'generateProto' |
| 43 | + |
| 44 | + // Wire the include proto directory from the extractIncludeProto task's actual output |
| 45 | + def extractTask = tasks.named('extractIncludeProto').get() |
| 46 | + def includeProtoDir = extractTask.destDir.get().asFile |
| 47 | + def includeProtoDirRel = projectDir.toPath().relativize(includeProtoDir.toPath()).toString() |
| 48 | + |
| 49 | + // Incremental build support: re-run when any file buf physically reads changes. |
| 50 | + // Include protos are not lint targets, but buf reads them for import resolution, |
| 51 | + // so they must be declared as inputs to keep the task cache hermetic. |
| 52 | + inputs.dir('src/main/protos') |
| 53 | + inputs.dir(includeProtoDir) |
| 54 | + inputs.file('protoLint.gradle') |
| 55 | + |
| 56 | + def markerFile = file("${buildDir}/tmp/protoLint.done") |
| 57 | + outputs.file(markerFile) |
| 58 | + |
| 59 | + doLast { |
| 60 | + def bufExe = configurations.bufTool.singleFile |
| 61 | + if (!bufExe.exists() || !bufExe.canExecute()) { |
| 62 | + bufExe.setExecutable(true) |
| 63 | + } |
| 64 | + |
| 65 | + // 1. Legacy Whitelist |
| 66 | + // Contains enums that existed before the 'UNKNOWN_' standard was enforced. |
| 67 | + // Format: "filename.proto:EnumName" or "filename.proto:MessageName.EnumName" |
| 68 | + def legacyEnums = [ |
| 69 | + "core/contract/common.proto:ResourceCode", |
| 70 | + "core/contract/smart_contract.proto:SmartContract.ABI.Entry.EntryType", |
| 71 | + "core/contract/smart_contract.proto:SmartContract.ABI.Entry.StateMutabilityType", |
| 72 | + "core/Tron.proto:AccountType", |
| 73 | + "core/Tron.proto:ReasonCode", |
| 74 | + "core/Tron.proto:Proposal.State", |
| 75 | + "core/Tron.proto:MarketOrder.State", |
| 76 | + "core/Tron.proto:Permission.PermissionType", |
| 77 | + "core/Tron.proto:Transaction.Contract.ContractType", |
| 78 | + "core/Tron.proto:Transaction.Result.code", |
| 79 | + "core/Tron.proto:Transaction.Result.contractResult", |
| 80 | + "core/Tron.proto:TransactionInfo.code", |
| 81 | + "core/Tron.proto:BlockInventory.Type", |
| 82 | + "core/Tron.proto:Inventory.InventoryType", |
| 83 | + "core/Tron.proto:Items.ItemType", |
| 84 | + "core/Tron.proto:PBFTMessage.MsgType", |
| 85 | + "core/Tron.proto:PBFTMessage.DataType", |
| 86 | + "api/api.proto:Return.response_code", |
| 87 | + "api/api.proto:TransactionSignWeight.Result.response_code", |
| 88 | + "api/api.proto:TransactionApprovedList.Result.response_code", |
| 89 | + "api/zksnark.proto:ZksnarkResponse.Code" |
| 90 | + ].collect { it.toString() } as Set |
| 91 | + |
| 92 | + // 2. Build JSON AST Image using buf CLI |
| 93 | + def imageDir = file("${buildDir}/tmp/buf") |
| 94 | + def imageFile = file("${imageDir}/proto-ast.json") |
| 95 | + imageDir.mkdirs() |
| 96 | + |
| 97 | + println "🔍 Generating Proto AST image using buf CLI..." |
| 98 | + |
| 99 | + def bufConfig = new JsonBuilder([version: "v1beta1", build: [roots: ["src/main/protos", includeProtoDirRel]]]).toString() |
| 100 | + |
| 101 | + def execResult = exec { |
| 102 | + commandLine bufExe.absolutePath, 'build', '.', '--config', bufConfig, '-o', "${imageFile.absolutePath}#format=json" |
| 103 | + ignoreExitValue = true |
| 104 | + } |
| 105 | + |
| 106 | + if (execResult.exitValue != 0) { |
| 107 | + throw new GradleException("Failed to generate AST image. Ensure your .proto files are valid. Buf exited with code ${execResult.exitValue}") |
| 108 | + } |
| 109 | + |
| 110 | + if (!imageFile.exists()) { |
| 111 | + throw new GradleException("Failed to locate generated buf image at ${imageFile.absolutePath}") |
| 112 | + } |
| 113 | + |
| 114 | + // 3. Parse AST and Validate Enums |
| 115 | + def descriptorSet |
| 116 | + try { |
| 117 | + descriptorSet = new JsonSlurper().parse(imageFile) |
| 118 | + } catch (Exception e) { |
| 119 | + throw new GradleException("Failed to parse buf generated JSON AST: ${e.message}", e) |
| 120 | + } |
| 121 | + |
| 122 | + def errors = [] |
| 123 | + |
| 124 | + descriptorSet.file?.each { protoFile -> |
| 125 | + // Skip Google's and gRPC's internal protos as they are outside our control |
| 126 | + if (protoFile.name?.startsWith("google/") || protoFile.name?.startsWith("grpc/")) { |
| 127 | + return |
| 128 | + } |
| 129 | + |
| 130 | + // A queue-based (BFS) approach to safely traverse all nested messages and enums |
| 131 | + // without using recursion, ensuring support for any nesting depth. |
| 132 | + Queue queue = new ArrayDeque() |
| 133 | + |
| 134 | + // Initial seed: top-level enums and messages |
| 135 | + protoFile.enumType?.each { queue.add([def: it, parentName: ""]) } |
| 136 | + protoFile.messageType?.each { queue.add([def: it, parentName: ""]) } |
| 137 | + |
| 138 | + while (!queue.isEmpty()) { |
| 139 | + def item = queue.poll() |
| 140 | + def definition = item.def |
| 141 | + def parentName = item.parentName |
| 142 | + |
| 143 | + // In buf's JSON image, enums expose EnumDescriptorProto.value while |
| 144 | + // message descriptors do not, so we use that field as the discriminator here. |
| 145 | + if (definition.value != null) { |
| 146 | + // This is an Enum definition |
| 147 | + def fullName = parentName ? "${parentName}.${definition.name}" : definition.name |
| 148 | + def identifier = "${protoFile.name}:${fullName}".toString() |
| 149 | + |
| 150 | + if (!legacyEnums.contains(identifier)) { |
| 151 | + def zeroValue = definition.value?.find { it.number == 0 } |
| 152 | + if (zeroValue && !zeroValue.name?.startsWith("UNKNOWN_")) { |
| 153 | + errors << "[${protoFile.name}] Enum \"${fullName}\" has index 0: \"${zeroValue.name}\". It MUST start with \"UNKNOWN_\"." |
| 154 | + } |
| 155 | + } |
| 156 | + } else { |
| 157 | + // This is a Message definition, look for nested enums and nested messages |
| 158 | + def currentMsgName = parentName ? "${parentName}.${definition.name}" : definition.name |
| 159 | + |
| 160 | + definition.enumType?.each { queue << [def: it, parentName: currentMsgName] } |
| 161 | + definition.nestedType?.each { queue << [def: it, parentName: currentMsgName] } |
| 162 | + } |
| 163 | + } |
| 164 | + } |
| 165 | + |
| 166 | + // 4. Report Results |
| 167 | + if (!errors.isEmpty()) { |
| 168 | + println "\n❌ [Protocol Design Violation] The following enums violate the java-tron API evolution standard (Issue #6515):" |
| 169 | + errors.each { println " - $it" } |
| 170 | + throw new GradleException("Proto Enum validation failed. See above for details.") |
| 171 | + } else { |
| 172 | + println "✅ Proto Enum validation passed!" |
| 173 | + // Update marker file for Gradle incremental build cache |
| 174 | + markerFile.text = "Success" |
| 175 | + } |
| 176 | + } |
| 177 | +} |
| 178 | + |
| 179 | +check.dependsOn protoLint |
0 commit comments