dohertj2/mxaccessgw
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
3081b80efc0acc3be6c989197599a0307564e53d
mxaccessgw/docs/audit/fragments/12-styleguides.md
T

11 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink