chore: update project structure, naming, and add reporting infrastructure

- Update all 7 phase docs with source/target location references (golang/ for Go source, dotnet/ for .NET version) - Rename NATS.Server to ZB.MOM.NatsNet.Server in phase 4-7 docs - Update solution layout to dotnet/src/ and dotnet/tests/ structure - Create CLAUDE.md with project summary and phase links - Update .gitignore: track porting.db, add standard .NET patterns - Add golang/nats-server as git submodule - Add reports/generate-report.sh and pre-commit hook - Add documentation_rules.md to version control
2026-02-26 06:38:56 -05:00
parent ca6ed0f09f
commit 8d68f63e6c
13 changed files with 547 additions and 63 deletions
--- a/docs/plans/phases/phase-1-decomposition.md
+++ b/docs/plans/phases/phase-1-decomposition.md
@@ -26,6 +26,13 @@ sqlite3 --version   # optional, any 3.x
 echo $CGO_ENABLED   # should print 1 (or be unset; we set it explicitly below)
 ```

+## Source and Target Locations
+
+| Component | Path |
+|---|---|
+| Go source code | `golang/` (specifically `golang/nats-server/`) |
+| .NET ported version | `dotnet/` |
+
 ## Steps

 ### Step 1: Initialize the porting database
--- a/docs/plans/phases/phase-2-verification.md
+++ b/docs/plans/phases/phase-2-verification.md
@@ -14,6 +14,13 @@ proceeding to library mapping and porting.
  analyzer run. If the source was updated, re-run the Phase 1 analyzer first.
 - `dotnet`, `sqlite3`, `find`, `grep`, and `wc` are available on your PATH.

+## Source and Target Locations
+
+| Component | Path |
+|---|---|
+| Go source code | `golang/` (specifically `golang/nats-server/`) |
+| .NET ported version | `dotnet/` |
+
 ## Steps

 ### Step 1: Generate the summary report
--- a/docs/plans/phases/phase-3-library-mapping.md
+++ b/docs/plans/phases/phase-3-library-mapping.md
@@ -13,6 +13,13 @@ returns an empty list and every import has a documented .NET migration path.
 - Familiarity with both the Go standard library and .NET BCL / NuGet ecosystem.
 - A working `dotnet` CLI for running PortTracker commands.

+## Source and Target Locations
+
+| Component | Path |
+|---|---|
+| Go source code | `golang/` (specifically `golang/nats-server/`) |
+| .NET ported version | `dotnet/` |
+
 ## Steps

 ### Step 1: List all unmapped libraries
--- a/docs/plans/phases/phase-4-dotnet-design.md
+++ b/docs/plans/phases/phase-4-dotnet-design.md
@@ -11,31 +11,38 @@ Every module, feature, and test in the porting database must have either a .NET
 - Phases 1-3 complete: all Go items in the DB, all libraries mapped
 - Verify with: `dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db`

+## Source and Target Locations
+
+- **Go source code** is located in the `golang/` folder (specifically `golang/nats-server/`)
+- **.NET ported version** is located in the `dotnet/` folder
+
 ## Solution Structure

 Define the .NET solution layout following standard conventions:

 ```
-src/
-  NATS.Server/                    # Main server library (all core logic)
-    Protocol/                     # Wire protocol parsing, commands
-    Subscriptions/                # SubList trie, subject matching
-    JetStream/                    # Stream management, consumers
-    Cluster/                      # Routes, gateways, leaf nodes
-    Auth/                         # Authentication, accounts, JWT
-    ...
-  NATS.Server.Host/               # Host/entry point (Program.cs, DI, config)
+dotnet/
+  ZB.MOM.NatsNet.sln
+  src/
+    ZB.MOM.NatsNet.Server/                    # Main server library (all core logic)
+      Protocol/                     # Wire protocol parsing, commands
+      Subscriptions/                # SubList trie, subject matching
+      JetStream/                    # Stream management, consumers
+      Cluster/                      # Routes, gateways, leaf nodes
+      Auth/                         # Authentication, accounts, JWT
+      ...
+    ZB.MOM.NatsNet.Server.Host/               # Host/entry point (Program.cs, DI, config)

-tests/
-  NATS.Server.Tests/              # Unit tests for NATS.Server
-    Protocol/
-    Subscriptions/
-    JetStream/
-    ...
-  NATS.Server.IntegrationTests/   # Cross-module and end-to-end tests
+  tests/
+    ZB.MOM.NatsNet.Server.Tests/              # Unit tests for ZB.MOM.NatsNet.Server
+      Protocol/
+      Subscriptions/
+      JetStream/
+      ...
+    ZB.MOM.NatsNet.Server.IntegrationTests/   # Cross-module and end-to-end tests
 ```

-The `NATS.Server` project holds all portable logic. `NATS.Server.Host` is the thin entry point that wires up dependency injection, configuration, and hosting. Tests mirror the source structure.
+The `ZB.MOM.NatsNet.Server` project holds all portable logic. `ZB.MOM.NatsNet.Server.Host` is the thin entry point that wires up dependency injection, configuration, and hosting. Tests mirror the source structure.

 ## Naming Conventions

@@ -45,11 +52,11 @@ Follow these rules consistently when mapping Go items to .NET:
 |--------|-----------|---------|
 | Classes | PascalCase | `NatsParser`, `SubList`, `JetStreamController` |
 | Methods | PascalCase | `TryParse`, `Match`, `ProcessMessage` |
-| Namespaces | `NATS.Server.[Module]` | `NATS.Server.Protocol`, `NATS.Server.Subscriptions` |
+| Namespaces | `ZB.MOM.NatsNet.Server.[Module]` | `ZB.MOM.NatsNet.Server.Protocol`, `ZB.MOM.NatsNet.Server.Subscriptions` |
 | Test classes | `[ClassName]Tests` | `NatsParserTests`, `SubListTests` |
 | Test methods | `[Method]_[Scenario]_[Expected]` | `TryParse_ValidInput_ReturnsTrue` |
 | Interfaces | `I[Name]` | `IMessageRouter`, `ISubListAccess` |
-| Projects | `NATS.Server[.Suffix]` | `NATS.Server`, `NATS.Server.Host` |
+| Projects | `ZB.MOM.NatsNet.Server[.Suffix]` | `ZB.MOM.NatsNet.Server`, `ZB.MOM.NatsNet.Server.Host` |

 Avoid abbreviations unless they are universally understood (e.g., `TCP`, `TLS`, `JWT`). Prefer descriptive names over short ones.

@@ -65,8 +72,8 @@ dotnet run --project tools/NatsNet.PortTracker -- module list --db porting.db

 # Map a module to its .NET target
 dotnet run --project tools/NatsNet.PortTracker -- module map <id> \
-  --project "NATS.Server" \
-  --namespace "NATS.Server.Protocol" \
+  --project "ZB.MOM.NatsNet.Server" \
+  --namespace "ZB.MOM.NatsNet.Server.Protocol" \
  --class "NatsParser" \
  --db porting.db
 ```
@@ -75,11 +82,11 @@ Work through all modules systematically. Group related Go files into the same na

 | Go package/file pattern | .NET namespace |
 |------------------------|----------------|
-| `server/parser.go` | `NATS.Server.Protocol` |
-| `server/sublist.go` | `NATS.Server.Subscriptions` |
-| `server/jetstream*.go` | `NATS.Server.JetStream` |
-| `server/route.go`, `server/gateway.go` | `NATS.Server.Cluster` |
-| `server/auth.go`, `server/accounts.go` | `NATS.Server.Auth` |
+| `server/parser.go` | `ZB.MOM.NatsNet.Server.Protocol` |
+| `server/sublist.go` | `ZB.MOM.NatsNet.Server.Subscriptions` |
+| `server/jetstream*.go` | `ZB.MOM.NatsNet.Server.JetStream` |
+| `server/route.go`, `server/gateway.go` | `ZB.MOM.NatsNet.Server.Cluster` |
+| `server/auth.go`, `server/accounts.go` | `ZB.MOM.NatsNet.Server.Auth` |
 | `server/pse/` | Likely N/A (Go-specific platform code) |

 ### Step 2: Map features
@@ -92,7 +99,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature list --module <module_

 # Map a feature
 dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \
-  --project "NATS.Server" \
+  --project "ZB.MOM.NatsNet.Server" \
  --class "NatsParser" \
  --method "TryParse" \
  --db porting.db
@@ -115,7 +122,7 @@ dotnet run --project tools/NatsNet.PortTracker -- test list --module <module_id>

 # Map a test
 dotnet run --project tools/NatsNet.PortTracker -- test map <id> \
-  --project "NATS.Server.Tests" \
+  --project "ZB.MOM.NatsNet.Server.Tests" \
  --class "NatsParserTests" \
  --method "TryParse_ValidInput_ReturnsTrue" \
  --db porting.db
@@ -147,7 +154,7 @@ Items that typically do not need a .NET port:
 |---------|--------|
 | `pse_darwin.go`, `pse_linux.go`, `pse_windows.go` | Go-specific platform syscall wrappers; use .NET `System.Diagnostics.Process` instead |
 | `disk_avail_windows.go`, `disk_avail_linux.go` | Go-specific disk APIs; use .NET `System.IO.DriveInfo` instead |
-| Custom logger (`logger.go`, `log.go`) | Replaced by Serilog via `NATS.Server.Host` |
+| Custom logger (`logger.go`, `log.go`) | Replaced by Serilog via `ZB.MOM.NatsNet.Server.Host` |
 | Signal handling (`signal.go`) | Replaced by .NET Generic Host `IHostLifetime` |
 | Go `sync.Pool`, `sync.Map` wrappers | .NET has `ObjectPool<T>`, `ConcurrentDictionary<K,V>` built-in |
 | Build tags / `_test.go` helpers specific to Go test infra | Replaced by xUnit attributes and test fixtures |
--- a/docs/plans/phases/phase-5-mapping-verification.md
+++ b/docs/plans/phases/phase-5-mapping-verification.md
@@ -11,6 +11,11 @@ Confirm zero unmapped items, validate all N/A justifications, enforce naming con
 - Phase 4 complete: all items have .NET mappings or N/A status
 - Verify with: `dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db`

+## Source and Target Locations
+
+- **Go source code** is located in the `golang/` folder (specifically `golang/nats-server/`)
+- **.NET ported version** is located in the `dotnet/` folder
+
 ## Steps

 ### Step 1: Confirm zero unmapped items
@@ -71,13 +76,13 @@ dotnet run --project tools/NatsNet.PortTracker -- module list --db porting.db
 dotnet run --project tools/NatsNet.PortTracker -- feature list --module <id> --db porting.db
 ```

-**Namespace hierarchy check**: Namespaces must follow `NATS.Server.[Module]` pattern:
+**Namespace hierarchy check**: Namespaces must follow `ZB.MOM.NatsNet.Server.[Module]` pattern:

 | Valid | Invalid |
 |-------|---------|
-| `NATS.Server.Protocol` | `Protocol` (missing root) |
-| `NATS.Server.JetStream` | `NATS.Server.jetstream` (wrong case) |
-| `NATS.Server.Subscriptions` | `NATSServer.Subscriptions` (wrong root) |
+| `ZB.MOM.NatsNet.Server.Protocol` | `Protocol` (missing root) |
+| `ZB.MOM.NatsNet.Server.JetStream` | `ZB.MOM.NatsNet.Server.jetstream` (wrong case) |
+| `ZB.MOM.NatsNet.Server.Subscriptions` | `NATSServer.Subscriptions` (wrong root) |

 **Test naming check**: Test classes must end in `Tests`. Test methods must follow `[Method]_[Scenario]_[Expected]` pattern:

@@ -115,14 +120,14 @@ If collisions are found, rename one of the conflicting methods. Common resolutio
 Verify that test mappings reference the correct test project:

 ```bash
-# All tests should target NATS.Server.Tests or NATS.Server.IntegrationTests
+# All tests should target ZB.MOM.NatsNet.Server.Tests or ZB.MOM.NatsNet.Server.IntegrationTests
 dotnet run --project tools/NatsNet.PortTracker -- test list --db porting.db
 ```

 Check that:
- Unit tests point to `NATS.Server.Tests`
- Integration tests (if any) point to `NATS.Server.IntegrationTests`
- No tests accidentally point to `NATS.Server` (the library project)
+- Unit tests point to `ZB.MOM.NatsNet.Server.Tests`
+- Integration tests (if any) point to `ZB.MOM.NatsNet.Server.IntegrationTests`
+- No tests accidentally point to `ZB.MOM.NatsNet.Server` (the library project)

 ### Step 6: Run phase check

@@ -181,7 +186,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \
 - Zero items in `not_started` status without a .NET mapping
 - All N/A items have a documented, valid reason
 - All `dotnet_class` and `dotnet_method` values follow PascalCase
- All namespaces follow `NATS.Server.[Module]` hierarchy
+- All namespaces follow `ZB.MOM.NatsNet.Server.[Module]` hierarchy
 - No two features map to the same class + method combination
 - All tests target the correct test project
 - `phase check 5` passes with no errors
--- a/docs/plans/phases/phase-6-porting.md
+++ b/docs/plans/phases/phase-6-porting.md
@@ -10,13 +10,18 @@ Implement every non-N/A module, feature, and test in the porting database. Work

 - Phase 5 complete: all mappings verified, no collisions, naming validated
 - .NET solution structure created:
-  - `src/NATS.Server/NATS.Server.csproj`
-  - `src/NATS.Server.Host/NATS.Server.Host.csproj`
-  - `tests/NATS.Server.Tests/NATS.Server.Tests.csproj`
-  - `tests/NATS.Server.IntegrationTests/NATS.Server.IntegrationTests.csproj`
+  - `dotnet/src/ZB.MOM.NatsNet.Server/ZB.MOM.NatsNet.Server.csproj`
+  - `dotnet/src/ZB.MOM.NatsNet.Server.Host/ZB.MOM.NatsNet.Server.Host.csproj`
+  - `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ZB.MOM.NatsNet.Server.Tests.csproj`
+  - `dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/ZB.MOM.NatsNet.Server.IntegrationTests.csproj`
 - Library dependencies (NuGet packages) added per Phase 3 mappings
 - Verify readiness: `dotnet run --project tools/NatsNet.PortTracker -- phase check 5 --db porting.db`

+## Source and Target Locations
+
+- **Go source code** is located in the `golang/` folder (specifically `golang/nats-server/`)
+- **.NET ported version** is located in the `dotnet/` folder
+
 ## Porting Workflow

 This is the core loop. Repeat until all items are complete.
@@ -44,7 +49,7 @@ dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status s
 In the .NET project, create the class and method skeleton based on the mapping:

 1. Look up the mapping: `dotnet run --project tools/NatsNet.PortTracker -- feature show <id> --db porting.db`
-2. Create the file at the correct path under `src/NATS.Server/` following the namespace hierarchy
+2. Create the file at the correct path under `dotnet/src/ZB.MOM.NatsNet.Server/` following the namespace hierarchy
 3. Add the class declaration, method signature, and a `throw new NotImplementedException()` body

 For batch scaffolding of an entire module:
@@ -95,8 +100,8 @@ dotnet run --project tools/NatsNet.PortTracker -- feature update <id> --status c
 If tests exist for this feature, run them:

 ```bash
-dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \
-  tests/NATS.Server.Tests/
+dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \
+  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
 ```

 Fix any failures before moving on.
--- a/docs/plans/phases/phase-7-porting-verification.md
+++ b/docs/plans/phases/phase-7-porting-verification.md
@@ -12,6 +12,11 @@ Every ported module passes its targeted tests. Every item in the database reache
 - All tests ported and compilable
 - Verify readiness: `dotnet run --project tools/NatsNet.PortTracker -- phase check 6 --db porting.db`

+## Source and Target Locations
+
+- **Go source code** is located in the `golang/` folder (specifically `golang/nats-server/`)
+- **.NET ported version** is located in the `dotnet/` folder
+
 ## Verification Workflow

 Work through modules one at a time. Do not move to the next module until the current one is fully verified.
@@ -41,16 +46,16 @@ Run only the tests for this module using `dotnet test --filter`:

 ```bash
 # Filter by namespace (matches all tests in the module's namespace)
-dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \
-  tests/NATS.Server.Tests/
+dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \
+  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/

 # Filter by test class
-dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests" \
-  tests/NATS.Server.Tests/
+dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests" \
+  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/

 # Filter by specific test method
-dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests.TryParse_ValidInput_ReturnsTrue" \
-  tests/NATS.Server.Tests/
+dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests.TryParse_ValidInput_ReturnsTrue" \
+  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
 ```

 The `--filter` flag uses partial matching on the fully qualified test name. Use the namespace pattern for module-wide runs, and the class or method pattern for debugging specific failures.
@@ -67,13 +72,13 @@ When tests fail:
 3. **Compare Go and .NET logic.** Open the Go source at the stored line number. Check for translation errors: off-by-one, missing edge cases, different default values.
 4. **Fix and re-run.** After fixing, re-run only the failing test:
   ```bash
-   dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol.NatsParserTests.TryParse_EmptyInput_ReturnsFalse" \
-     tests/NATS.Server.Tests/
+   dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol.NatsParserTests.TryParse_EmptyInput_ReturnsFalse" \
+     dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
   ```
 5. **Then re-run the full module.** Confirm no regressions:
   ```bash
-   dotnet test --filter "FullyQualifiedName~NATS.Server.Tests.Protocol" \
-     tests/NATS.Server.Tests/
+   dotnet test --filter "FullyQualifiedName~ZB.MOM.NatsNet.Server.Tests.Protocol" \
+     dotnet/tests/ZB.MOM.NatsNet.Server.Tests/
   ```

 Common failure causes:
@@ -117,7 +122,7 @@ After all modules are individually verified, run integration tests that exercise
 ### Step 7: Run integration tests

 ```bash
-dotnet test tests/NATS.Server.IntegrationTests/
+dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/
 ```

 Integration tests cover scenarios like:
@@ -142,7 +147,7 @@ Run both the Go server and the .NET server with the same workload and compare be
   ```
 2. Start the .NET server:
   ```bash
-   dotnet run --project src/NATS.Server.Host -- --port 4223
+   dotnet run --project dotnet/src/ZB.MOM.NatsNet.Server.Host -- --port 4223
   ```

 **Comparison scenarios:**
@@ -221,8 +226,8 @@ The issue is at a module boundary. Check:
 - All non-N/A modules have status `verified`
 - All non-N/A features have status `verified`
 - All non-N/A tests have status `verified`
- All targeted tests pass: `dotnet test tests/NATS.Server.Tests/`
- All integration tests pass: `dotnet test tests/NATS.Server.IntegrationTests/`
+- All targeted tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/`
+- All integration tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/`
 - Key behavioral scenarios produce equivalent results on Go and .NET servers
 - `phase check 7` passes with no errors
 - Final report exported and reviewed