natsnet/docs/plans/phases/phase-5-mapping-verification.md

# 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`
- Naming verification must check compliance with the [.NET Coding Standards](../../standards/dotnet-standards.md)

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

## Milestone Tracking

This phase corresponds to **Milestone 5** in [Gitea](https://gitea.dohertylan.com/dohertj2/natsnet/milestone/5). When starting this phase, verify the milestone is open. Assign relevant issues to this milestone as work progresses.

### Issue Updates

Each completion criterion has a corresponding Gitea issue. Update issues as you work:

- **Starting a criterion**: Add a comment noting work has begun
- **Blocked**: Add a comment describing the blocker
- **Complete**: Close the issue with a comment summarizing the result (e.g., counts, verification output)

Close issues via CLI:
```bash
curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/issues/{N}" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $GITEA_TOKEN" \
  -d '{"state":"closed"}'
```
Or close via the Gitea web UI.

## 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 `ZB.MOM.NatsNet.Server.[Module]` pattern:

| Valid | Invalid |
|-------|---------|
| `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:

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

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

- [ ] [#31](https://gitea.dohertylan.com/dohertj2/natsnet/issues/31) Zero items in `not_started` status without a .NET mapping
- [ ] [#32](https://gitea.dohertylan.com/dohertj2/natsnet/issues/32) All N/A items have a documented, valid reason
- [ ] [#33](https://gitea.dohertylan.com/dohertj2/natsnet/issues/33) All `dotnet_class` and `dotnet_method` values follow PascalCase
- [ ] [#34](https://gitea.dohertylan.com/dohertj2/natsnet/issues/34) All namespaces follow `ZB.MOM.NatsNet.Server.[Module]` hierarchy
- [ ] [#35](https://gitea.dohertylan.com/dohertj2/natsnet/issues/35) No two features map to the same class + method combination
- [ ] [#36](https://gitea.dohertylan.com/dohertj2/natsnet/issues/36) All tests target the correct test project
- [ ] [#37](https://gitea.dohertylan.com/dohertj2/natsnet/issues/37) `phase check 5` passes with no errors
- [ ] [#38](https://gitea.dohertylan.com/dohertj2/natsnet/issues/38) Mapping report exported and reviewed
- [ ] Close the Phase 5 milestone in Gitea:
  ```bash
  curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/milestones/5" \
    -H "Content-Type: application/json" \
    -H "Authorization: token $GITEA_TOKEN" \
    -d '{"state":"closed"}'
  ```
  Or close it via the Gitea web UI at https://gitea.dohertylan.com/dohertj2/natsnet/milestone/5

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