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
This commit is contained in:
Joseph Doherty
2026-02-26 06:38:56 -05:00
parent ca6ed0f09f
commit 8d68f63e6c
13 changed files with 547 additions and 63 deletions

View File

@@ -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