# Cluster 12 — Style Guides Docs audited: `StyleGuide.md`, `REVIEW-PROCESS.md`, `docs/style-guides/CSharpStyleGuide.md`, `docs/style-guides/GoStyleGuide.md`, `docs/style-guides/JavaStyleGuide.md`, `docs/style-guides/ProtobufStyleGuide.md`, `docs/style-guides/PythonStyleGuide.md`, `docs/style-guides/RustStyleGuide.md`. --- DOC: StyleGuide.md LINES: 3 CLAIM: "This guide defines writing conventions and formatting rules for all ScadaBridge documentation." CLAIM_TYPE: term VERDICT: wrong EVIDENCE: StyleGuide.md:3; no file in the repo uses "ScadaBridge" as the project name — the project is `mxaccessgw` / MXAccess Gateway throughout every other file. CODE_AREA: style.docs SEVERITY: high PROPOSED_FIX: flag only — replace "ScadaBridge" with "MXAccess Gateway" / `mxaccessgw`. --- DOC: StyleGuide.md LINES: 12, 15, 76, 100–105, 144, 147, 154–155, 161, 215–217, 226–227, 246–248, 263 CLAIM: Examples throughout use `ScadaGatewayActor`, `ScadaClientActor`, `TemplateInstanceActor`, `ReceiveActor`, `IRequiredActor`, `IActorRef`, configuration key `ScadaBridge:Timeout`, file path `src/Infrastructure/Akka/Actors/`, and documentation paths `../Akka/Actors.md`, `../Akka/HealthChecks.md`, `../Configuration/Akka.md`. CLAIM_TYPE: cross-ref VERDICT: wrong EVIDENCE: None of these types, paths, or configuration keys exist anywhere in the `mxaccessgw` repository. The "Akka" actor framework is not used in this project. `ls /Users/dohertj2/Desktop/mxaccessgateway/` shows no `Akka/` directory. The referenced paths (`../Akka/Actors.md`, `./Configuration.md`, `./Patterns.md`) are all dead links. CODE_AREA: style.docs SEVERITY: high PROPOSED_FIX: flag only — the entire examples section was copied from a different (Akka-based) project. All example types, paths, and configuration keys must be replaced with MXAccess Gateway equivalents. --- DOC: StyleGuide.md LINES: 90 CLAIM: "Supported languages: `csharp`, `json`, `bash`, `xml`, `sql`, `yaml`, `html`, `css`, `javascript`" CLAIM_TYPE: term VERDICT: stale EVIDENCE: Corpus-wide count of code-block language identifiers in `docs/` (via grep): `powershell` (42 uses), `text` (48 uses), `rust` (12), `python` (12), `go` (7), `proto`/`protobuf` (6) are all actively used but not listed. `yaml` and `javascript` appear zero times. The list is both under-inclusive and includes unused entries. CODE_AREA: style.docs SEVERITY: low PROPOSED_FIX: flag only — update the list to reflect languages actually used in the docs corpus; at minimum add `powershell`, `text`, `rust`, `python`, `go`, `proto`; optionally remove `yaml` and `javascript`. --- DOC: docs/style-guides/JavaStyleGuide.md LINES: 25 CLAIM: "Use lowercase package names under `com.dohertylan.mxgateway`." CLAIM_TYPE: config-key VERDICT: wrong EVIDENCE: Every handwritten Java source file in `clients/java/` uses the package root `com.zb.mom.ww.mxgateway` (confirmed by inspecting `clients/java/zb-mom-ww-mxgateway-client/src/main/java/com/zb/mom/ww/mxgateway/client/MxGatewayClient.java` and sibling files). No file uses `com.dohertylan`. CODE_AREA: style.java SEVERITY: high PROPOSED_FIX: flag only — change the prescribed package root to `com.zb.mom.ww.mxgateway` to match the actual codebase. --- DOC: docs/style-guides/PythonStyleGuide.md LINES: 27–29 CLAIM: "Put library code under `src/mxgateway/`. Put CLI entry points under `src/mxgateway_cli/`. Keep generated protobuf modules under a clearly named `generated` package." CLAIM_TYPE: path VERDICT: wrong EVIDENCE: Actual package directories are `clients/python/src/zb_mom_ww_mxgateway/` and `clients/python/src/zb_mom_ww_mxgateway_cli/` (confirmed by `ls clients/python/src/`). The short names `mxgateway` and `mxgateway_cli` do not exist on disk. The generated package is correctly at `src/zb_mom_ww_mxgateway/generated/` (matches the rule in spirit, but the parent path is wrong). CODE_AREA: style.python SEVERITY: medium PROPOSED_FIX: flag only — update the stated package paths to `src/zb_mom_ww_mxgateway/` and `src/zb_mom_ww_mxgateway_cli/`. --- DOC: docs/style-guides/GoStyleGuide.md LINES: 68 CLAIM: "Keep integration tests behind `MXGATEWAY_INTEGRATION=1` or build tags." CLAIM_TYPE: config-key VERDICT: unverifiable EVIDENCE: No Go source file in `clients/go/` references `MXGATEWAY_INTEGRATION`; no build tag gating for integration was found. The existing Go tests (`clients/go/mxgateway/*_test.go`) all use in-process fakes via `bufconn`, so no live integration tests appear to exist yet. The rule is prescriptive (correct direction) but the env-var name cannot be confirmed against practice because live tests are absent. CODE_AREA: style.go SEVERITY: low PROPOSED_FIX: flag only. --- DOC: docs/style-guides/PythonStyleGuide.md LINES: 68 CLAIM: "Keep live integration tests behind `MXGATEWAY_INTEGRATION=1`." CLAIM_TYPE: config-key VERDICT: stale EVIDENCE: The only opt-in env var actually used in `clients/python/tests/` is `MXGATEWAY_RUN_TLS_TESTS=1` (confirmed in `tests/test_tls.py:36`). There is no usage of `MXGATEWAY_INTEGRATION=1` in the Python test tree. The same inconsistency holds for Java (`clients/java/`) and Rust (`clients/rust/`), where no opt-in env-var pattern for live tests was found at all. CODE_AREA: style.python SEVERITY: low PROPOSED_FIX: flag only — standardize the prescribed env var with what the test code actually uses; consider aligning Go, Java, Rust, Python on a single variable name. --- DOC: docs/style-guides/JavaStyleGuide.md LINES: 65 CLAIM: "Keep live gateway tests behind `MXGATEWAY_INTEGRATION=1` and JUnit assumptions." CLAIM_TYPE: config-key VERDICT: unverifiable EVIDENCE: No Java test file in `clients/java/` references `MXGATEWAY_INTEGRATION`. The Java test classes (`MxGatewayClientSessionTests.java`, etc.) use in-process gRPC servers. No live-gateway test gating was found in the Java client tree. CODE_AREA: style.java SEVERITY: low PROPOSED_FIX: flag only. --- DOC: docs/style-guides/RustStyleGuide.md LINES: 65 CLAIM: "Keep live gateway tests behind `MXGATEWAY_INTEGRATION=1`." CLAIM_TYPE: config-key VERDICT: unverifiable EVIDENCE: No Rust source file in `clients/rust/` references `MXGATEWAY_INTEGRATION`. The existing Rust tests (`tests/client_behavior.rs`) use a fake `tonic` in-process server. No live-gateway gating was found. CODE_AREA: style.rust SEVERITY: low PROPOSED_FIX: flag only. --- DOC: REVIEW-PROCESS.md LINES: 14 CLAIM: "For a `src/` project, `` is the project name with the `ZB.MOM.WW.MxGateway.` prefix stripped — `src/ZB.MOM.WW.MxGateway.Server` is reviewed in `code-reviews/Server/`." CLAIM_TYPE: path VERDICT: accurate EVIDENCE: `ls /Users/dohertj2/Desktop/mxaccessgateway/src/` confirms project names `ZB.MOM.WW.MxGateway.{Server,Worker,Contracts,Tests,Worker.Tests,IntegrationTests}`; `ls /Users/dohertj2/Desktop/mxaccessgateway/code-reviews/` shows folders `Server`, `Worker`, `Tests`, `Worker.Tests`, `IntegrationTests`, `Contracts`, `Client.*`. Mapping is accurate. CODE_AREA: style.crossref SEVERITY: low PROPOSED_FIX: accurate — no action needed. --- DOC: REVIEW-PROCESS.md LINES: 68–69 CLAIM: Test projects are `src/ZB.MOM.WW.MxGateway.Tests`, `src/ZB.MOM.WW.MxGateway.Worker.Tests`, `src/ZB.MOM.WW.MxGateway.IntegrationTests`. CLAIM_TYPE: path VERDICT: accurate EVIDENCE: All three directories exist under `src/` (confirmed by `ls /Users/dohertj2/Desktop/mxaccessgateway/src/`). CODE_AREA: style.crossref SEVERITY: low PROPOSED_FIX: accurate — no action needed. --- DOC: REVIEW-PROCESS.md LINES: 77–78 CLAIM: Entry format is in `[code-reviews/_template/findings.md](code-reviews/_template/findings.md)`. CLAIM_TYPE: path VERDICT: accurate EVIDENCE: File exists at `/Users/dohertj2/Desktop/mxaccessgateway/code-reviews/_template/findings.md`. CODE_AREA: style.crossref SEVERITY: low PROPOSED_FIX: accurate — no action needed. --- DOC: REVIEW-PROCESS.md LINES: 120–127 CLAIM: "`python code-reviews/regen-readme.py`" regenerates the README; `regen-readme.py --check` validates it; `scripts/check-code-reviews-readme.ps1` is the CI hook. CLAIM_TYPE: command VERDICT: accurate EVIDENCE: `code-reviews/regen-readme.py` exists; `scripts/check-code-reviews-readme.ps1` exists; the `code-reviews/README.md` header confirms generation ("GENERATED FILE — do not edit by hand. Regenerate with: `python code-reviews/regen-readme.py`"). CODE_AREA: style.crossref SEVERITY: low PROPOSED_FIX: accurate — no action needed. --- DOC: docs/style-guides/CSharpStyleGuide.md LINES: 11 ("Prefer file-scoped namespaces"), 12 ("Prefer `sealed` classes unless inheritance is required") CLAIM: These are the established conventions in the codebase. CLAIM_TYPE: behavior-rule VERDICT: accurate EVIDENCE: Spot-checked `src/` C# files: all non-generated namespace declarations use the file-scoped `namespace X.Y;` form (grep of block-scoped `namespace` without semicolon returns only generated/obj files). 249 `public sealed class` declarations found vs. exactly 1 bare `public class` (a test fixture `GatewayLogRedactorSeamTests`). Convention is well-followed. CODE_AREA: style.csharp SEVERITY: low PROPOSED_FIX: accurate — no action needed. --- DOC: docs/style-guides/GoStyleGuide.md LINES: 13 CLAIM: "Keep generated protobuf code under `internal/generated` unless the public API intentionally exposes it." CLAIM_TYPE: path VERDICT: accurate EVIDENCE: `clients/go/internal/generated/` exists and contains generated code (confirmed by `find /Users/dohertj2/Desktop/mxaccessgateway/clients/go -type d`). CODE_AREA: style.go SEVERITY: low PROPOSED_FIX: accurate — no action needed. --- DOC: docs/style-guides/RustStyleGuide.md LINES: 49, 42 CLAIM: "Use `thiserror` for library error enums." / "Use `async` APIs with `tokio` for network operations." CLAIM_TYPE: behavior-rule VERDICT: accurate EVIDENCE: `clients/rust/Cargo.toml` lists `thiserror = "2.0.17"` and `tokio = { version = "1.48.0", ... }` as workspace dependencies. CODE_AREA: style.rust SEVERITY: low PROPOSED_FIX: accurate — no action needed. --- ## Summary ### Counts by verdict | Verdict | Count | |----------------|-------| | wrong | 3 | | stale | 2 | | unverifiable | 3 | | accurate | 6 | | **Total** | **14** | ### Counts by severity | Severity | Count | |----------|-------| | high | 3 | | medium | 1 | | low | 10 | ### High-severity findings - **StyleGuide.md line 3 (wrong/high):** The guide's opening sentence names "ScadaBridge" as the project — a stale copy-paste from a different codebase. The term does not appear anywhere else in the repo. - **StyleGuide.md lines 12–263 (wrong/high):** All illustrative examples (types, file paths, doc cross-references, configuration keys) are from an Akka-actor project (`ScadaGatewayActor`, `ReceiveActor`, `IActorRef`, `../Akka/Actors.md`, `ScadaBridge:Timeout`, etc.). None exist in the MXAccess Gateway codebase. Every linked path is a dead reference. - **JavaStyleGuide.md line 25 (wrong/high):** Prescribed Java package root `com.dohertylan.mxgateway` does not match the actual code, which universally uses `com.zb.mom.ww.mxgateway`.