From 810ef29dbbaa4c3933509b10e2e0483fecbae7c3 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 27 Feb 2026 04:49:21 -0500 Subject: [PATCH] docs: add feature status audit design Design for classifying 3394 unknown features against their .NET implementations in batches of 50, using PortTracker batch-update with mandatory dry-run before execution. --- .../2026-02-27-feature-status-audit-design.md | 106 ++++++++++++++++++ reports/current.md | 4 +- reports/report_01df4cc.md | 35 ++++++ 3 files changed, 143 insertions(+), 2 deletions(-) create mode 100644 docs/plans/2026-02-27-feature-status-audit-design.md create mode 100644 reports/report_01df4cc.md diff --git a/docs/plans/2026-02-27-feature-status-audit-design.md b/docs/plans/2026-02-27-feature-status-audit-design.md new file mode 100644 index 0000000..3f302cb --- /dev/null +++ b/docs/plans/2026-02-27-feature-status-audit-design.md @@ -0,0 +1,106 @@ +# Feature Status Audit Design + +**Date:** 2026-02-27 +**Status:** Approved + +## Problem + +3394 features in module 8 (`server`) are marked as `unknown` status after a bulk reclassification. Each needs to be checked against its .NET implementation to determine the correct status. + +## Scope + +- **Module:** 8 (server) — all 3394 unknown features +- **Go source files:** 64 distinct files +- **All features have `dotnet_class` and `dotnet_method` mappings** — no unmapped features + +## Classification Criteria + +| Status | Criteria | Example | +|--------|----------|---------| +| `verified` | .NET method exists with non-trivial logic matching Go behavior | `MemStore.StoreRawMsg` — full implementation | +| `stub` | .NET method exists but is `throw new NotImplementedException()`, empty, or only partially implemented | `FileStore.Compact` — no real logic | +| `n_a` | Go feature doesn't apply to .NET — .NET uses a different approach (different library, runtime feature, or platform pattern) | Go logging functions → .NET uses `Microsoft.Extensions.Logging` | +| `deferred` | .NET method doesn't exist, or classification requires running the server end-to-end | Server-integration features needing full runtime | + +**Partial implementations** (method exists with some logic but missing significant functionality) are classified as `stub`. + +## Batch Execution Process + +Features are processed in fixed batches of 50. Each batch follows this workflow: + +### Step 1: Fetch next 50 unknown features + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status unknown --db porting.db +``` + +Take the first 50 IDs from the output. + +### Step 2: Inspect .NET source for each feature + +For each feature: +1. Read the `dotnet_class` and `dotnet_method` from the feature record +2. Find the .NET source file containing that class +3. Check the method body: + - Real logic matching Go = `verified` + - Stub / empty / partial = `stub` + - .NET alternative exists = `n_a` + - Method not found = `deferred` + +### Step 3: Dry-run the batch update (MANDATORY) + +Group features by their determined status and dry-run using PortTracker: + +```bash +# Dry-run — verify correct features affected +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids 150-160 --set-status deferred --db porting.db +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids 2068-2077 --set-status verified --db porting.db +``` + +Review the preview output. Only proceed if the listed features match expectations. + +### Step 4: Execute once dry-run verified + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids 150-160 --set-status deferred --execute --db porting.db +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids 2068-2077 --set-status verified --execute --db porting.db +``` + +### Step 5: Verify remaining count + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature list --status unknown --db porting.db +``` + +Confirm the count decreased by ~50. + +## Rules + +1. **ALWAYS dry-run before executing** — no exceptions +2. **NEVER use direct SQL** (`sqlite3`) — use PortTracker CLI exclusively +3. **Process exactly 50 per batch** (or fewer if fewer remain) +4. **Report classification breakdown** after each batch (e.g. "Batch 3: 12 verified, 30 stub, 3 n_a, 5 deferred") +5. **68 batches total** (3394 / 50 = ~68) + +## Key .NET Source Locations + +``` +dotnet/src/ZB.MOM.NatsNet.Server/ + Accounts/Account.cs, AccountResolver.cs, DirJwtStore.cs + Auth/AuthHandler.cs, JwtProcessor.cs + Config/ReloadOptions.cs, ServerOptionsConfiguration.cs + JetStream/MemStore.cs, FileStore.cs, JetStreamTypes.cs + JetStream/NatsStream.cs, NatsConsumer.cs, RaftTypes.cs + Protocol/ProtocolParser.cs, ProxyProtocol.cs + Routes/RouteTypes.cs, LeafNode/LeafNodeTypes.cs, Gateway/GatewayTypes.cs + Mqtt/MqttHandler.cs, WebSocket/WebSocketTypes.cs + Internal/ (various data structures) + NatsServer.cs, NatsServer.*.cs (partial class files) + ClientConnection.cs +``` + +## Non-Goals + +- No code changes — this is classification only +- No unit_tests reclassification (separate effort) +- No schema changes needed (`unknown` already added) diff --git a/reports/current.md b/reports/current.md index ae80037..43451c7 100644 --- a/reports/current.md +++ b/reports/current.md @@ -1,6 +1,6 @@ # NATS .NET Porting Status Report -Generated: 2026-02-27 09:45:24 UTC +Generated: 2026-02-27 09:49:21 UTC ## Modules (12 total) @@ -12,7 +12,7 @@ Generated: 2026-02-27 09:45:24 UTC | Status | Count | |--------|-------| -| deferred | 3394 | +| unknown | 3394 | | verified | 279 | ## Unit Tests (3257 total) diff --git a/reports/report_01df4cc.md b/reports/report_01df4cc.md new file mode 100644 index 0000000..43451c7 --- /dev/null +++ b/reports/report_01df4cc.md @@ -0,0 +1,35 @@ +# NATS .NET Porting Status Report + +Generated: 2026-02-27 09:49:21 UTC + +## Modules (12 total) + +| Status | Count | +|--------|-------| +| verified | 12 | + +## Features (3673 total) + +| Status | Count | +|--------|-------| +| unknown | 3394 | +| verified | 279 | + +## Unit Tests (3257 total) + +| Status | Count | +|--------|-------| +| deferred | 2680 | +| n_a | 187 | +| verified | 390 | + +## Library Mappings (36 total) + +| Status | Count | +|--------|-------| +| mapped | 36 | + + +## Overall Progress + +**868/6942 items complete (12.5%)**