dohertj2/natsnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add phase 4-7 instruction guides

Browse Source
This commit is contained in:
Joseph Doherty
2026-02-26 06:23:13 -05:00
parent 1bc64cf36e
commit ca6ed0f09f
4 changed files with 864 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
docs/plans/phases/phase-5-mapping-verification.md Normal file
View File

@@ -0,0 +1,193 @@
# Phase 5: Mapping Verification
Verify that every Go item in the porting database is either mapped to a .NET target or justified as N/A. This phase is a quality gate between design (Phase 4) and implementation (Phase 6).
## Objective
Confirm zero unmapped items, validate all N/A justifications, enforce naming conventions, and detect collisions. The porting database must be a complete, consistent blueprint before any code is written.
## Prerequisites
- 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`
## Steps
### Step 1: Confirm zero unmapped items
Run the summary report and verify that no items remain in `not_started` status without a .NET mapping:
```bash
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
```
The output shows counts per status. All items should be in one of these categories:
- `not_started` with .NET mapping fields populated (ready for Phase 6)
- `n_a` with a reason in the notes field
If any items lack both a mapping and N/A status, go back to Phase 4 and address them.
### Step 2: Review N/A items
Every N/A item must have a justification. Review them by type:
```bash
# Review N/A modules
dotnet run --project tools/NatsNet.PortTracker -- module list --status n_a --db porting.db
# Review N/A features
dotnet run --project tools/NatsNet.PortTracker -- feature list --status n_a --db porting.db
# Review N/A tests
dotnet run --project tools/NatsNet.PortTracker -- test list --status n_a --db porting.db
```
For each N/A item, verify:
1. The reason is documented (check with `module show <id>`, `feature show <id>`, or `test show <id>`)
2. The reason is valid (the item genuinely has no .NET equivalent or is replaced by a .NET facility)
3. No dependent items rely on this N/A item being ported
```bash
# Check if anything depends on an N/A item
dotnet run --project tools/NatsNet.PortTracker -- dependency show module <id> --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- dependency show feature <id> --db porting.db
```
If a non-N/A item depends on an N/A item, either the dependency needs to be resolved differently or the N/A classification is wrong.
### Step 3: Verify naming conventions
Walk through the mappings and check for naming compliance:
**PascalCase check**: All `dotnet_class` and `dotnet_method` values must use PascalCase. No `snake_case`, no `camelCase`.
```bash
# List all mapped modules and spot-check names
dotnet run --project tools/NatsNet.PortTracker -- module list --db porting.db
# List all mapped features for a module and check class/method names
dotnet run --project tools/NatsNet.PortTracker -- feature list --module <id> --db porting.db
```
**Namespace hierarchy check**: Namespaces must follow `NATS.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) |
**Test naming check**: Test classes must end in `Tests`. Test methods must follow `[Method]_[Scenario]_[Expected]` pattern:
| Valid | Invalid |
|-------|---------|
| `NatsParserTests` | `ParserTest` (wrong suffix) |
| `TryParse_ValidInput_ReturnsTrue` | `TestParserValid` (Go-style naming) |
| `Match_WildcardSubject_ReturnsSubscribers` | `test_match` (snake_case) |
### Step 4: Check for collisions
No two features should map to the same class + method combination. This would cause compile errors or overwrite conflicts.
```bash
# Export the full mapping report for review
dotnet run --project tools/NatsNet.PortTracker -- report export --format md --output porting-mapping-report.md --db porting.db
```
Open `porting-mapping-report.md` and search for duplicate class + method pairs. If the database is large, run a targeted SQL query:
```bash
sqlite3 porting.db "
SELECT dotnet_class, dotnet_method, COUNT(*) as cnt
FROM features
WHERE dotnet_class IS NOT NULL AND dotnet_method IS NOT NULL
GROUP BY dotnet_class, dotnet_method
HAVING cnt > 1;
"
```
If collisions are found, rename one of the conflicting methods. Common resolution: add a more specific suffix (`ParseHeaders` vs `ParseBody` instead of two `Parse` methods).
### Step 5: Validate cross-references
Verify that test mappings reference the correct test project:
```bash
# All tests should target NATS.Server.Tests or NATS.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)
### Step 6: Run phase check
Run the built-in phase verification:
```bash
dotnet run --project tools/NatsNet.PortTracker -- phase check 5 --db porting.db
```
This runs automated checks and reports any remaining issues. All checks must pass.
### Step 7: Export final mapping report
Generate the definitive mapping report that serves as the implementation reference for Phase 6:
```bash
dotnet run --project tools/NatsNet.PortTracker -- report export \
--format md \
--output porting-mapping-report.md \
--db porting.db
```
Review the exported report for completeness. This document becomes the source of truth for the porting work.
## Troubleshooting
### Unmapped items found
```bash
# Find features with no .NET mapping and not N/A
dotnet run --project tools/NatsNet.PortTracker -- feature list --status not_started --db porting.db
```
For each unmapped item, either map it (Phase 4 Step 2) or set it to N/A with a reason.
### N/A item has dependents
If a non-N/A feature depends on an N/A feature:
1. Determine if the dependency is real or an artifact of the Go call graph
2. If real, the N/A classification is likely wrong -- map the item instead
3. If the dependency is Go-specific, remove or reclassify it
### Naming collision detected
Rename one of the colliding methods to be more specific:
```bash
dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \
--method "ParseHeadersFromBuffer" \
--db porting.db
```
## Completion Criteria
- 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
- No two features map to the same class + method combination
- All tests target the correct test project
- `phase check 5` passes with no errors
- Mapping report exported and reviewed
## Related Documentation
- [Phase 4: .NET Solution Design](phase-4-dotnet-design.md) -- the mapping phase this verifies
- [Phase 6: Porting](phase-6-porting.md) -- uses the verified mappings for implementation