Joseph Doherty
227 lines
11 KiB
Markdown
227 lines
11 KiB
Markdown
# 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<T>`, `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, `<Module>` 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`.
|