fix(archreview): CI pipeline + codegen freshness guards (IPC-01/09/19/20, TST-03)

- IPC-01: regenerate the stale client descriptor set and add ClientProtoInputTests (semantic, protoc-free) so a missing contract symbol fails the build. - IPC-20: make publish-client-proto-inputs.ps1 -Check source_code_info-normalized so it is protoc-version tolerant. - IPC-19: document + guard the "Generated/ must be committed for net48" rule (docs/Contracts.md, csproj comment, check-codegen.ps1). - IPC-09: harden the per-client generate-proto scripts (PATH resolution + pinned grpcio/protobuf/java version asserts) so regeneration is reproducible. - TST-03: add .gitea/workflows/ci.yml (portable/java/windows/live jobs) running the build, tests, client checks, and the codegen guards. - Also: check-codegen.ps1 Check 3 guards the CLI-02 vendored Rust protos against drift. archreview: IPC-01/09/19/20 Done, TST-03 In review (pipeline authored + validated, not yet run on a Gitea runner). Verified on macOS: NonWindows build clean, ClientProtoInputTests 5/5, -Check exit 0.
2026-07-09 06:17:56 -04:00
parent 219fa6ddb4
commit d5248f61a2
13 changed files with 645 additions and 47 deletions
@@ -5,25 +5,46 @@ $repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
 $protoRoot = Join-Path $repoRoot 'src\ZB.MOM.WW.MxGateway.Contracts\Protos'
 $outputRoot = Join-Path $PSScriptRoot 'internal\generated'
 $modulePath = 'gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated'
-$protoc = 'C:\Users\dohertj2\AppData\Local\Microsoft\WinGet\Packages\Google.Protobuf_Microsoft.Winget.Source_8wekyb3d8bbwe\bin\protoc.exe'
-$goPluginPath = 'C:\Users\dohertj2\go\bin'

-if (-not (Test-Path $protoc)) {
-    throw "protoc was not found at $protoc. See docs/ToolchainLinks.md."
-}
+function Resolve-Tool {
+    # Resolve a codegen tool from PATH first (portable), then the documented Windows fallbacks,
+    # instead of the previous hard-coded per-machine paths. See docs/ToolchainLinks.md.
+    param(
+        [string[]]$Names,
+        [string[]]$FallbackPaths
+    )

-foreach ($pluginName in @('protoc-gen-go.exe', 'protoc-gen-go-grpc.exe')) {
-    $pluginPath = Join-Path $goPluginPath $pluginName
-    if (-not (Test-Path $pluginPath)) {
-        throw "$pluginName was not found at $pluginPath. See docs/ToolchainLinks.md."
+    foreach ($name in $Names) {
+        $cmd = Get-Command $name -ErrorAction SilentlyContinue
+        if ($null -ne $cmd) {
+            return $cmd.Source
+        }
    }
+
+    foreach ($fallback in $FallbackPaths) {
+        if ($fallback -and (Test-Path $fallback)) {
+            return $fallback
+        }
+    }
+
+    throw "Could not find $($Names -join '/') on PATH. See docs/ToolchainLinks.md."
 }

+$wingetProtoc = if ($env:LOCALAPPDATA) {
+    Join-Path $env:LOCALAPPDATA 'Microsoft\WinGet\Packages\Google.Protobuf_Microsoft.Winget.Source_8wekyb3d8bbwe\bin\protoc.exe'
+} else { $null }
+$goBin = if ($env:USERPROFILE) { Join-Path $env:USERPROFILE 'go\bin' } elseif ($env:HOME) { Join-Path $env:HOME 'go/bin' } else { $null }
+
+$protoc = Resolve-Tool -Names @('protoc', 'protoc.exe') -FallbackPaths @($wingetProtoc)
+$protocGenGo = Resolve-Tool -Names @('protoc-gen-go', 'protoc-gen-go.exe') -FallbackPaths @((if ($goBin) { Join-Path $goBin 'protoc-gen-go.exe' }), (if ($goBin) { Join-Path $goBin 'protoc-gen-go' }))
+$protocGenGoGrpc = Resolve-Tool -Names @('protoc-gen-go-grpc', 'protoc-gen-go-grpc.exe') -FallbackPaths @((if ($goBin) { Join-Path $goBin 'protoc-gen-go-grpc.exe' }), (if ($goBin) { Join-Path $goBin 'protoc-gen-go-grpc' }))
+
+# protoc discovers the plugins on PATH; prepend the directories the resolved plugins live in.
+$env:Path = (Split-Path $protocGenGo -Parent) + [System.IO.Path]::PathSeparator + (Split-Path $protocGenGoGrpc -Parent) + [System.IO.Path]::PathSeparator + $env:Path
+
 New-Item -ItemType Directory -Path $outputRoot -Force | Out-Null
 Get-ChildItem -Path $outputRoot -Filter '*.pb.go' -File | Remove-Item

-$env:Path = "$goPluginPath;$env:Path"
-
 & $protoc `
    --proto_path=$protoRoot `
    --go_out=$outputRoot `
@@ -35,6 +56,10 @@ $env:Path = "$goPluginPath;$env:Path"
    mxaccess_worker.proto `
    galaxy_repository.proto

+if ($LASTEXITCODE -ne 0) {
+    throw "protoc (go) failed with exit code $LASTEXITCODE."
+}
+
 & $protoc `
    --proto_path=$protoRoot `
    --go-grpc_out=$outputRoot `
@@ -44,3 +69,6 @@ $env:Path = "$goPluginPath;$env:Path"
    mxaccess_gateway.proto `
    galaxy_repository.proto

+if ($LASTEXITCODE -ne 0) {
+    throw "protoc (go-grpc) failed with exit code $LASTEXITCODE."
+}
@@ -57,3 +57,35 @@ protobuf {
        }
    }
 }
+
+// IPC-09 guard: the generated Java tree is tracked (generatedFilesBaseDir above points at the
+// committed src/main/generated). `gradle build` regenerates it, so an un-regenerated .proto change,
+// or a plugin/protobuf version bump, silently drifts the committed output. checkGeneratedClean
+// fails when the regenerated tree differs from what is committed.
+//
+// Caveat (repo memory project_java_generated_churn): the protobuf gradle plugin also rewrites
+// MxaccessGateway.java with a spurious protobuf-runtime-version delta on every build even when no
+// .proto changed. CI reverts that one file (git checkout) before invoking this task; locally, do the
+// same when you did not touch a .proto. See docs/GatewayTesting.md "Continuous Integration".
+tasks.register('checkGeneratedClean') {
+    group = 'verification'
+    description = 'Fails if the committed generated Java tree differs from a fresh regeneration.'
+    dependsOn 'generateProto'
+    doLast {
+        def generatedDir = 'clients/java/src/main/generated'
+        def stdout = new ByteArrayOutputStream()
+        def result = exec {
+            workingDir = rootProject.projectDir.parentFile.parentFile
+            commandLine 'git', 'status', '--porcelain', '--', generatedDir
+            standardOutput = stdout
+            ignoreExitValue = true
+        }
+        def dirty = stdout.toString().trim()
+        if (!dirty.isEmpty()) {
+            throw new GradleException(
+                "Generated Java is stale or churned:\n${dirty}\n" +
+                "Regenerate and commit after a .proto change, or 'git checkout' the spurious " +
+                "MxaccessGateway.java protobuf-version churn when no .proto changed.")
+        }
+    }
+}
@@ -1,15 +1,52 @@
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'

+# Pinned generator baseline. The committed Python bindings are stamped with
+# GRPC_GENERATED_VERSION = 1.80.0 and "Protobuf Python Version: 6.31.1". A newer grpcio-tools
+# stamps a higher GRPC_GENERATED_VERSION than the pinned grpcio runtime (pyproject.toml:
+# grpcio>=1.80,<2), which makes _pb2_grpc import raise at runtime and breaks pytest. Regeneration
+# MUST use this exact grpcio-tools version. See docs/ClientProtoGeneration.md and the repo memory
+# project_python_client_regen_pin.
+$PinnedGrpcioToolsVersion = '1.80.0'
+
 $repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
 $protoRoot = Join-Path $repoRoot 'src\ZB.MOM.WW.MxGateway.Contracts\Protos'
 $outputRoot = Join-Path $PSScriptRoot 'src\zb_mom_ww_mxgateway\generated'
-$python = 'C:\Users\dohertj2\AppData\Local\Programs\Python\Python312\python.exe'

-if (-not (Test-Path $python)) {
-    throw "Python was not found at $python. See docs/ToolchainLinks.md."
+function Resolve-Python {
+    # Prefer python on PATH (python on Windows, python3 on Linux/macOS), then the documented
+    # Windows install location. Avoids the previous hard-coded per-machine path.
+    foreach ($name in @('python', 'python3', 'python.exe')) {
+        $cmd = Get-Command $name -ErrorAction SilentlyContinue
+        if ($null -ne $cmd) {
+            return $cmd.Source
+        }
+    }
+
+    if ($env:LOCALAPPDATA) {
+        $documentedPath = Join-Path $env:LOCALAPPDATA 'Programs\Python\Python312\python.exe'
+        if (Test-Path $documentedPath) {
+            return $documentedPath
+        }
+    }
+
+    throw 'Could not find python on PATH. See docs/ToolchainLinks.md.'
 }

+function Assert-GrpcioToolsVersion {
+    param([string]$Python)
+
+    $version = (& $Python -c 'import grpc_tools; from importlib.metadata import version; print(version("grpcio-tools"))').Trim()
+    if ($version -ne $PinnedGrpcioToolsVersion) {
+        throw "grpcio-tools $version is installed, but regeneration is pinned to $PinnedGrpcioToolsVersion. " +
+            "Install the pin (python -m pip install 'grpcio-tools==$PinnedGrpcioToolsVersion') before regenerating, " +
+            "or the generated bindings will stamp a GRPC_GENERATED_VERSION the pinned grpcio runtime rejects."
+    }
+}
+
+$python = Resolve-Python
+Assert-GrpcioToolsVersion -Python $python
+
 New-Item -ItemType Directory -Path $outputRoot -Force | Out-Null
 Get-ChildItem -Path (Join-Path $outputRoot '*_pb2.py') -File | Remove-Item
 Get-ChildItem -Path (Join-Path $outputRoot '*_pb2_grpc.py') -File | Remove-Item
@@ -21,3 +58,7 @@ Get-ChildItem -Path (Join-Path $outputRoot '*_pb2_grpc.py') -File | Remove-Item
    mxaccess_gateway.proto `
    mxaccess_worker.proto `
    galaxy_repository.proto
+
+if ($LASTEXITCODE -ne 0) {
+    throw "grpc_tools.protoc failed with exit code $LASTEXITCODE."
+}
@@ -38,6 +38,9 @@ Issues = "https://gitea.dohertylan.com/dohertj2/mxaccessgw/issues"

 [project.optional-dependencies]
 dev = [
+  # Runtime range for local dev, but REGENERATION is pinned to grpcio-tools==1.80.0
+  # (protobuf 6.31.1): a newer version stamps a GRPC_GENERATED_VERSION the pinned grpcio
+  # runtime rejects and breaks pytest. generate-proto.ps1 asserts the exact pin.
  "grpcio-tools>=1.80,<2",
  "pytest>=9,<10",
  "pytest-asyncio>=1.3,<2",