docs(audit): cluster findings fragments (13 clusters, read-only verification)
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,341 @@
|
||||
# Cluster 11 — Clients
|
||||
|
||||
Auditor: automated read-only audit
|
||||
Date: 2026-06-03
|
||||
Scope: clients/dotnet, clients/go, clients/java, clients/python, clients/rust — README.md, *ClientDesign.md; docs/ClientLibrariesDesign.md; docs/ClientPackaging.md
|
||||
|
||||
---
|
||||
|
||||
DOC: docs/ClientPackaging.md
|
||||
LINES: 51–52
|
||||
CLAIM: Build and test commands reference `clients/dotnet/ZB.MOM.WW.MxGateway.Client.sln` (`.sln` extension)
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx:1 — only a `.slnx` file exists; no `.sln` file is present
|
||||
CODE_AREA: client.dotnet
|
||||
SEVERITY: high
|
||||
PROPOSED_FIX: Replace `.sln` with `.slnx` in both `dotnet build` and `dotnet test` lines: `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` / `dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx --no-build`
|
||||
|
||||
---
|
||||
|
||||
DOC: docs/ClientPackaging.md
|
||||
LINES: 159–160
|
||||
CLAIM: "The Python package is `mxaccess-gateway-client`. Generated modules live under `clients/python/src/mxgateway/generated`."
|
||||
CLAIM_TYPE: config-key
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/python/pyproject.toml:6 — `name = "zb-mom-ww-mxaccess-gateway-client"`; clients/python/src/zb_mom_ww_mxgateway/generated/ — actual generated path
|
||||
CODE_AREA: client.python
|
||||
SEVERITY: high
|
||||
PROPOSED_FIX: Correct both: package name → `zb-mom-ww-mxaccess-gateway-client`; generated path → `clients/python/src/zb_mom_ww_mxgateway/generated`
|
||||
|
||||
---
|
||||
|
||||
DOC: docs/ClientPackaging.md
|
||||
LINES: 187
|
||||
CLAIM: `python -m mxgateway_cli version --json`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/python/src/zb_mom_ww_mxgateway_cli/__main__.py — actual module is `zb_mom_ww_mxgateway_cli`; clients/python/pyproject.toml:48 — entry point `zb_mom_ww_mxgateway_cli.commands:main`
|
||||
CODE_AREA: client.python
|
||||
SEVERITY: high
|
||||
PROPOSED_FIX: Replace with `python -m zb_mom_ww_mxgateway_cli version --json`
|
||||
|
||||
---
|
||||
|
||||
DOC: docs/ClientPackaging.md
|
||||
LINES: 193–194, 201, 217, 225–227
|
||||
CLAIM: Java workspace uses `mxgateway-client` and `mxgateway-cli` as subproject names; Gradle task paths use `:mxgateway-client:generateProto`, `:mxgateway-client:jar`, `:mxgateway-cli:installDist`, `:mxgateway-cli:run`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/java/settings.gradle:25–26 — `include 'zb-mom-ww-mxgateway-client'` and `include 'zb-mom-ww-mxgateway-cli'`; Gradle task paths are derived from subproject names
|
||||
CODE_AREA: client.java
|
||||
SEVERITY: high
|
||||
PROPOSED_FIX: Replace all `:mxgateway-client:` references with `:zb-mom-ww-mxgateway-client:` and `:mxgateway-cli:` with `:zb-mom-ww-mxgateway-cli:` throughout ClientPackaging.md
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/rust/README.md
|
||||
LINES: 65
|
||||
CLAIM: `cargo run -p mxgw-cli -- stream-alarms --session-id <session-id> --max-messages 1 --json`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/rust/crates/mxgw-cli/src/main.rs:282–295 — `StreamAlarms` struct has fields `filter_prefix`, `max_events`, `json`, `jsonl` (via `ConnectionArgs`); no `session_id`, flag is `--max-events` not `--max-messages`
|
||||
CODE_AREA: client.rust
|
||||
SEVERITY: high
|
||||
PROPOSED_FIX: Replace with `cargo run -p mxgw-cli -- stream-alarms --max-events 1 --json` (no `--session-id`; change `--max-messages` to `--max-events`)
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/rust/README.md
|
||||
LINES: 66
|
||||
CLAIM: `cargo run -p mxgw-cli -- acknowledge-alarm --session-id <session-id> --alarm-reference "\\Galaxy\Area001.Pump001.PumpFault" --json`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/rust/crates/mxgw-cli/src/main.rs:298–311 — `AcknowledgeAlarm` struct has fields `reference`, `comment`, `operator`, `json` (via `ConnectionArgs`); flag is `--reference` not `--alarm-reference`, and `session_id` is absent
|
||||
CODE_AREA: client.rust
|
||||
SEVERITY: high
|
||||
PROPOSED_FIX: Replace with `cargo run -p mxgw-cli -- acknowledge-alarm --reference "\\Galaxy\Area001.Pump001.PumpFault" --json`
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/go/README.md
|
||||
LINES: 143
|
||||
CLAIM: `import pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated/galaxy_repository/v1"`
|
||||
CLAIM_TYPE: path
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/go/internal/generated/ — flat directory; all .pb.go files are `package generated`. Actual import path used in library code: `"gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"` (clients/go/mxgateway/galaxy.go:11, types.go:3, session.go:13)
|
||||
CODE_AREA: client.go
|
||||
SEVERITY: high
|
||||
PROPOSED_FIX: Replace the import path with `pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"` (drop the `/galaxy_repository/v1` suffix)
|
||||
|
||||
---
|
||||
|
||||
DOC: docs/ClientLibrariesDesign.md
|
||||
LINES: 410
|
||||
CLAIM: Python generated code lives under `clients/python/src/mxgateway/generated`
|
||||
CLAIM_TYPE: path
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/python/src/zb_mom_ww_mxgateway/generated/ — actual path; no `mxgateway` directory under `src/`
|
||||
CODE_AREA: client.python
|
||||
SEVERITY: high
|
||||
PROPOSED_FIX: Replace with `clients/python/src/zb_mom_ww_mxgateway/generated`
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/dotnet/DotnetClientDesign.md
|
||||
LINES: 35–36
|
||||
CLAIM: Layout includes `ZB.MOM.WW.MxGateway.Client.IntegrationTests/` project
|
||||
CLAIM_TYPE: path
|
||||
VERDICT: wrong
|
||||
EVIDENCE: `ls clients/dotnet/` — directory does not exist; `.slnx` file (clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx:9–11) contains only three projects (Client, Cli, Tests)
|
||||
CODE_AREA: client.dotnet
|
||||
SEVERITY: medium
|
||||
PROPOSED_FIX: Remove the `ZB.MOM.WW.MxGateway.Client.IntegrationTests/` entry from the layout section, or note it as "not yet created"
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/python/PythonClientDesign.md
|
||||
LINES: 215
|
||||
CLAIM: "Publishable package name should be stable, for example: `mxaccess-gateway-client`"
|
||||
CLAIM_TYPE: config-key
|
||||
VERDICT: stale
|
||||
EVIDENCE: clients/python/pyproject.toml:6 — actual name is `zb-mom-ww-mxaccess-gateway-client`; the "example" name was never adopted
|
||||
CODE_AREA: client.python
|
||||
SEVERITY: medium
|
||||
PROPOSED_FIX: Update the example to `zb-mom-ww-mxaccess-gateway-client` to reflect the chosen name
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/dotnet/DotnetClientDesign.md
|
||||
LINES: 55
|
||||
CLAIM: "`Grpc.Tools` for generation" listed as an expected package
|
||||
CLAIM_TYPE: config-key
|
||||
VERDICT: stale
|
||||
EVIDENCE: clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj — no `Grpc.Tools` reference; the client uses a project reference to the shared contracts csproj for generated types. clients/dotnet/README.md:17 correctly notes this is "reserved for future use"
|
||||
CODE_AREA: client.dotnet
|
||||
SEVERITY: medium
|
||||
PROPOSED_FIX: Remove `Grpc.Tools` from the "Expected packages" list or qualify it as "future, if client-local generation is adopted"
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/go/GoClientDesign.md
|
||||
LINES: 28–30
|
||||
CLAIM: `internal/generated/` contains only `mxaccess_gateway.pb.go` and `mxaccess_gateway_grpc.pb.go`
|
||||
CLAIM_TYPE: path
|
||||
VERDICT: stale
|
||||
EVIDENCE: clients/go/internal/generated/ — 5 files present: `galaxy_repository.pb.go`, `galaxy_repository_grpc.pb.go`, `mxaccess_gateway.pb.go`, `mxaccess_gateway_grpc.pb.go`, `mxaccess_worker.pb.go`
|
||||
CODE_AREA: client.go
|
||||
SEVERITY: medium
|
||||
PROPOSED_FIX: Add the missing galaxy_repository and mxaccess_worker generated files to the layout listing
|
||||
|
||||
---
|
||||
|
||||
DOC: docs/ClientPackaging.md
|
||||
LINES: 116
|
||||
CLAIM: "The Rust workspace builds the `mxgateway-client` library crate and the `mxgw` CLI crate."
|
||||
CLAIM_TYPE: term
|
||||
VERDICT: wrong
|
||||
EVIDENCE: clients/rust/Cargo.toml:2 — `name = "zb-mom-ww-mxgateway-client"`; crates/mxgw-cli/Cargo.toml:4 — package name `mxgw-cli`, binary name `mxgw`
|
||||
CODE_AREA: client.rust
|
||||
SEVERITY: medium
|
||||
PROPOSED_FIX: Change "mxgateway-client" to "zb-mom-ww-mxgateway-client" (the library crate name); "mxgw CLI crate" is acceptable since the binary is named `mxgw`
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/rust/RustClientDesign.md
|
||||
LINES: 278
|
||||
CLAIM: `mxgw stream-alarms [--filter-prefix <prefix>] [--max-events <n>]`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/rust/crates/mxgw-cli/src/main.rs:282–295 — `StreamAlarms` struct has `filter_prefix: Option<String>`, `max_events: usize`; test at line 2053 confirms `--max-events` flag name
|
||||
CODE_AREA: client.rust
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only — design doc is accurate; the discrepancy is in README.md (already captured above)
|
||||
|
||||
---
|
||||
|
||||
DOC: docs/ClientPackaging.md
|
||||
LINES: (no entry)
|
||||
CLAIM: (gap) `scripts/pack-clients.ps1` — the canonical multi-language pack and publish script — is not mentioned in ClientPackaging.md
|
||||
CLAIM_TYPE: behavior-rule
|
||||
VERDICT: gap
|
||||
EVIDENCE: scripts/pack-clients.ps1:1–40 — packs all five clients into `dist/`, supports `-Publish` to upload to Gitea feeds; ClientPackaging.md has no reference to it
|
||||
CODE_AREA: client.packaging
|
||||
SEVERITY: medium
|
||||
PROPOSED_FIX: Add a "Packing all clients at once" section to ClientPackaging.md pointing to `scripts/pack-clients.ps1` with the example invocations from the script's `.SYNOPSIS`
|
||||
|
||||
---
|
||||
|
||||
DOC: docs/ClientPackaging.md
|
||||
LINES: (no entry for Python build method)
|
||||
CLAIM: (gap) Python README and ClientPackaging.md document `pip wheel . --no-deps` as the build command; `scripts/pack-clients.ps1` uses `python -m build` (the PEP 517 standard tool). The dev dependency `build>=1.2,<2` is listed in pyproject.toml but the README's wheel command bypasses it.
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: gap
|
||||
EVIDENCE: clients/python/pyproject.toml:43 — `"build>=1.2,<2"` in dev deps; scripts/pack-clients.ps1:156 — `python -m build`; clients/python/README.md:43 — `pip wheel . --no-deps`
|
||||
CODE_AREA: client.python
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: Note in Python README and ClientPackaging.md that `python -m build` (using the `build` package already in dev deps) is the canonical wheel-build method; `pip wheel` is an alternative
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/java/README.md
|
||||
LINES: 37
|
||||
CLAIM: `gradle :zb-mom-ww-mxgateway-client:generateProto`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/java/settings.gradle:25 — `include 'zb-mom-ww-mxgateway-client'`; build.gradle:4 — `id 'com.google.protobuf'` applied to that subproject
|
||||
CODE_AREA: client.java
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/java/README.md
|
||||
LINES: 314
|
||||
CLAIM: `implementation 'com.zb.mom.ww.mxgateway:zb-mom-ww-mxgateway-client:0.1.0'`
|
||||
CLAIM_TYPE: config-key
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/java/build.gradle:15–16 — `group = 'com.zb.mom.ww.mxgateway'`, `version = '0.1.0'`; subproject name `zb-mom-ww-mxgateway-client` is the artifact ID
|
||||
CODE_AREA: client.java
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/rust/README.md
|
||||
LINES: 83
|
||||
CLAIM: "tonic 0.13.1 exposes no public hook to inject a custom certificate verifier"
|
||||
CLAIM_TYPE: version
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/rust/Cargo.toml:40 — `tonic = { version = "0.13.1", features = ["transport", "tls-ring"] }`
|
||||
CODE_AREA: client.rust
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/dotnet/README.md
|
||||
LINES: 22–23
|
||||
CLAIM: Build and test with `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` / `dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx --no-build`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx:1 — file exists with `.slnx` extension
|
||||
CODE_AREA: client.dotnet
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/dotnet/README.md
|
||||
LINES: 331
|
||||
CLAIM: `dotnet add package ZB.MOM.WW.MxGateway.Client --version 0.1.0`
|
||||
CLAIM_TYPE: version
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/dotnet/Directory.Build.props:14 — `<Version>0.1.0</Version>`; clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj:21 — `<PackageId>ZB.MOM.WW.MxGateway.Client</PackageId>`
|
||||
CODE_AREA: client.dotnet
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/go/README.md
|
||||
LINES: 292, 297
|
||||
CLAIM: `go get gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go@v0.1.0`; import `"gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/mxgateway"`
|
||||
CLAIM_TYPE: path
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/go/go.mod:1 — `module gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go`; `mxgateway/` subdirectory exists
|
||||
CODE_AREA: client.go
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/go/README.md
|
||||
LINES: 310–312
|
||||
CLAIM: `pwsh scripts/tag-go-module.ps1 -Version v0.1.1 -Push` creates an annotated tag `clients/go/v0.1.1`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: accurate
|
||||
EVIDENCE: scripts/tag-go-module.ps1:39 — `$tag = "clients/go/$Version"`; line 54 — `git tag -a $tag`; line 25–29 — `-Version` and `-Push` parameters exist
|
||||
CODE_AREA: client.go
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/python/README.md
|
||||
LINES: 288–290
|
||||
CLAIM: `pip install --index-url https://gitea.dohertylan.com/api/packages/dohertj2/pypi/simple/ zb-mom-ww-mxaccess-gateway-client`
|
||||
CLAIM_TYPE: path
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/python/pyproject.toml:6 — `name = "zb-mom-ww-mxaccess-gateway-client"` matches the pip install name
|
||||
CODE_AREA: client.python
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/rust/README.md
|
||||
LINES: 257–274
|
||||
CLAIM: Gitea Cargo registry at `sparse+https://gitea.dohertylan.com/api/packages/dohertj2/cargo/`, registry name `dohertj2-gitea`, crate `zb-mom-ww-mxgateway-client = { version = "0.1.0", registry = "dohertj2-gitea" }`
|
||||
CLAIM_TYPE: path
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/rust/Cargo.toml:14 — `publish = ["dohertj2-gitea"]`; version = "0.1.0"; registry name matches
|
||||
CODE_AREA: client.rust
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/java/README.md
|
||||
LINES: 297–299
|
||||
CLAIM: Maven feed at `https://gitea.dohertylan.com/api/packages/dohertj2/maven`; publish via `gradle :zb-mom-ww-mxgateway-client:publish`
|
||||
CLAIM_TYPE: path
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/java/build.gradle:72 — `url = 'https://gitea.dohertylan.com/api/packages/dohertj2/maven'`; `maven-publish` plugin applied to `zb-mom-ww-mxgateway-client`
|
||||
CODE_AREA: client.java
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/go/README.md
|
||||
LINES: 39–40
|
||||
CLAIM: Build and test with `go test ./...` / `go build ./...` / `go vet ./...` from `clients/go`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/go/go.mod:1 — module root at clients/go; standard Go toolchain commands apply
|
||||
CODE_AREA: client.go
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
|
||||
---
|
||||
|
||||
DOC: clients/java/README.md
|
||||
LINES: 265–267
|
||||
CLAIM: Build and test with `gradle test` from `clients/java`
|
||||
CLAIM_TYPE: command
|
||||
VERDICT: accurate
|
||||
EVIDENCE: clients/java/settings.gradle:25–26 — `include 'zb-mom-ww-mxgateway-client'` and `include 'zb-mom-ww-mxgateway-cli'`; root `build.gradle` applies `useJUnitPlatform()` to all java subprojects
|
||||
CODE_AREA: client.java
|
||||
SEVERITY: low
|
||||
PROPOSED_FIX: flag only
|
||||
Reference in New Issue
Block a user