From e7f259710a96a92946e4a433097d969af4b50299 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 27 Feb 2026 04:50:37 -0500 Subject: [PATCH] docs: add feature status audit implementation plan 68 batch tasks processing 50 features each. Each batch: fetch unknown features, inspect .NET source, classify, dry-run, execute via PortTracker CLI. --- .../2026-02-27-feature-status-audit-plan.md | 236 ++++++++++++++++++ ...27-feature-status-audit-plan.md.tasks.json | 9 + reports/current.md | 2 +- reports/report_810ef29.md | 35 +++ 4 files changed, 281 insertions(+), 1 deletion(-) create mode 100644 docs/plans/2026-02-27-feature-status-audit-plan.md create mode 100644 docs/plans/2026-02-27-feature-status-audit-plan.md.tasks.json create mode 100644 reports/report_810ef29.md diff --git a/docs/plans/2026-02-27-feature-status-audit-plan.md b/docs/plans/2026-02-27-feature-status-audit-plan.md new file mode 100644 index 0000000..417ea7e --- /dev/null +++ b/docs/plans/2026-02-27-feature-status-audit-plan.md @@ -0,0 +1,236 @@ +# Feature Status Audit Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task. + +**Goal:** Classify 3394 features currently marked `unknown` into the correct status (`verified`, `stub`, `n_a`, or `deferred`) by inspecting .NET source code against Go feature specifications. + +**Architecture:** Process features in sequential batches of 50. Each batch: fetch 50 unknown features via PortTracker CLI, inspect the corresponding .NET source files, classify each feature, dry-run the batch updates, then execute. Repeat until zero unknown features remain. + +**Tech Stack:** PortTracker CLI (`dotnet run --project tools/NatsNet.PortTracker`), .NET source at `dotnet/src/ZB.MOM.NatsNet.Server/` + +**Design doc:** `docs/plans/2026-02-27-feature-status-audit-design.md` + +--- + +## Important Rules (Read Before Every Task) + +1. **ALWAYS dry-run before executing** — no exceptions. Every `batch-update` command must be run WITHOUT `--execute` first to preview. +2. **NEVER use direct SQL** (`sqlite3`) — use the PortTracker CLI exclusively for all database operations. +3. **Process exactly 50 per batch** (or fewer if fewer remain in the final batch). +4. **Report classification breakdown** after each batch (e.g. "Batch 3: 12 verified, 30 stub, 3 n_a, 5 deferred"). + +## Classification Criteria Reference + +| Status | Criteria | +|--------|----------| +| `verified` | .NET method exists with non-trivial logic that matches the Go implementation's behavior | +| `stub` | .NET method exists but is `throw new NotImplementedException()`, empty, or only **partially** implemented (has structure but missing significant logic) | +| `n_a` | Go feature doesn't apply to .NET — .NET uses a different approach (e.g. Go logging → .NET uses `Microsoft.Extensions.Logging`) | +| `deferred` | .NET method doesn't exist at all, or classification requires the server running end-to-end | + +## Key .NET Source Locations + +When looking for a `dotnet_class`, search in these directories: + +``` +dotnet/src/ZB.MOM.NatsNet.Server/ + Accounts/ — Account, AccountResolver, DirJwtStore, AccountTypes + Auth/ — AuthHandler, JwtProcessor, CipherSuites, AuthTypes + Config/ — ReloadOptions, ServerOptionsConfiguration, NatsJsonConverters + Events/ — EventTypes + Gateway/ — GatewayTypes + Internal/ — Subscription, WaitGroup, ClosedRingBuffer, RateCounter, DataStructures/ + JetStream/ — MemStore, ConsumerMemStore, FileStore, FileStoreTypes, MessageBlock + JetStreamTypes, JetStreamApiTypes, JetStreamErrors, JetStreamVersioning + NatsStream, NatsConsumer, RaftTypes, JetStreamClusterTypes + LeafNode/ — LeafNodeTypes + MessageTrace/ — MsgTraceTypes + Monitor/ — MonitorTypes, MonitorSortOptions + Mqtt/ — MqttConstants, MqttTypes, MqttHandler + Protocol/ — ParserTypes, ProtocolParser, ProxyProtocol + Routes/ — RouteTypes + WebSocket/ — WebSocketConstants, WebSocketTypes + NatsServer.cs, NatsServer.Auth.cs, NatsServer.Signals.cs, NatsServer.Init.cs + NatsServer.Accounts.cs, NatsServer.Lifecycle.cs, NatsServer.Listeners.cs + ClientConnection.cs, ClientTypes.cs, NatsMessageHeaders.cs +``` + +--- + +### Task 0: Verify starting state and PortTracker commands + +**Files:** None — verification only. + +**Step 1: Check how many unknown features exist** + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status unknown --db porting.db +``` + +Expected: Output shows ~3394 features. Note the total count at the bottom. + +**Step 2: Verify batch-update dry-run works** + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids 150-152 --set-status verified --db porting.db +``` + +Expected: Preview output showing 3 features. Should say "Would affect 3 items:" and "Add --execute to apply these changes." Do NOT execute — this is just confirming the tool works. + +**Step 3: Record the starting count** + +Note the total unknown count. This is your baseline. After all batches complete, the count should be 0. + +--- + +### Task N (repeat for N=1 through 68): Process batch of 50 unknown features + +> **This task is a template.** Repeat it until zero unknown features remain. Each execution processes the next 50. + +**Files:** None — classification only, no code changes. + +**Step 1: Fetch the next 50 unknown features** + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status unknown --db porting.db +``` + +From the output, take the **first 50 feature IDs**. Note the `dotnet_class` and `dotnet_method` columns for each. + +**Step 2: For each feature, inspect the .NET implementation** + +For each of the 50 features: + +1. **Find the .NET source file** — use `Grep` to search for the class: + ``` + Grep pattern: "class {dotnet_class}" path: dotnet/src/ZB.MOM.NatsNet.Server/ + ``` + +2. **Find the method** — search within that file for the method name: + ``` + Grep pattern: "{dotnet_method}" path: {the file found above} + ``` + +3. **Read the method body** — use `Read` to view the method implementation. + +4. **Classify the feature:** + - If the method has real, non-trivial logic matching the Go behavior → `verified` + - If the method is `throw new NotImplementedException()`, empty, or only partially there → `stub` + - If the Go feature has a .NET-native replacement (e.g., Go's custom logging → `Microsoft.Extensions.Logging`, Go's `sync.Mutex` → C#'s `Lock`) → `n_a` + - If the method doesn't exist in the .NET codebase at all → `deferred` + +**Efficiency tip:** Features from the same `dotnet_class` should be inspected together — read the .NET file once and classify all features from that class in the batch. + +**Step 3: Group IDs by classification result** + +After inspecting all 50, organize the IDs into groups: + +``` +verified_ids: 2068,2069,2070,2071,... +stub_ids: 2080,2081,... +n_a_ids: 2090,... +deferred_ids: 2095,2096,... +``` + +**Step 4: Dry-run each group (MANDATORY — DO NOT SKIP)** + +Run the dry-run for EACH status group. Review the output carefully. + +```bash +# Dry-run verified +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {verified_ids} --set-status verified --db porting.db + +# Dry-run stub +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {stub_ids} --set-status stub --db porting.db + +# Dry-run n_a (include reason in notes) +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {n_a_ids} --set-status n_a --set-notes "{reason}" --db porting.db + +# Dry-run deferred +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {deferred_ids} --set-status deferred --db porting.db +``` + +Check that: +- The feature names in the preview match what you inspected +- The count per group adds up to 50 (or the batch size) +- No unexpected features appear + +**Step 5: Execute each group** + +Only after verifying ALL dry-runs look correct: + +```bash +# Execute verified +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {verified_ids} --set-status verified --execute --db porting.db + +# Execute stub +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {stub_ids} --set-status stub --execute --db porting.db + +# Execute n_a (with notes) +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {n_a_ids} --set-status n_a --set-notes "{reason}" --execute --db porting.db + +# Execute deferred +dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {deferred_ids} --set-status deferred --execute --db porting.db +``` + +**Step 6: Verify remaining count decreased** + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature list --status unknown --db porting.db +``` + +Confirm the total decreased by ~50 from the previous batch. + +**Step 7: Report batch summary** + +Print: `Batch N: X verified, Y stub, Z n_a, W deferred (Total remaining: NNNN)` + +--- + +### Task 69: Final verification and report + +**Files:** None — verification only. + +**Step 1: Confirm zero unknown features remain** + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature list --status unknown --db porting.db +``` + +Expected: `Total: 0 features` + +**Step 2: Generate the full status breakdown** + +```bash +dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status verified --db porting.db +dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status stub --db porting.db +dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status n_a --db porting.db +dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status deferred --db porting.db +``` + +Note the count for each status. + +**Step 3: Generate updated porting report** + +```bash +./reports/generate-report.sh +``` + +**Step 4: Commit the updated report** + +```bash +git add reports/ +git commit -m "chore: update porting report after feature status audit" +``` + +**Step 5: Print final summary** + +``` +Feature Status Audit Complete +============================= +Total features audited: 3394 + verified: NNNN + stub: NNNN + n_a: NNNN + deferred: NNNN +``` diff --git a/docs/plans/2026-02-27-feature-status-audit-plan.md.tasks.json b/docs/plans/2026-02-27-feature-status-audit-plan.md.tasks.json new file mode 100644 index 0000000..1e4e966 --- /dev/null +++ b/docs/plans/2026-02-27-feature-status-audit-plan.md.tasks.json @@ -0,0 +1,9 @@ +{ + "planPath": "docs/plans/2026-02-27-feature-status-audit-plan.md", + "tasks": [ + {"id": 0, "subject": "Task 0: Verify starting state and PortTracker commands", "status": "pending"}, + {"id": 1, "subject": "Task 1-68: Process batches of 50 unknown features (repeating template)", "status": "pending", "blockedBy": [0], "note": "This is a repeating task — execute the template from the plan 68 times until 0 unknown features remain"}, + {"id": 69, "subject": "Task 69: Final verification and report", "status": "pending", "blockedBy": [1]} + ], + "lastUpdated": "2026-02-27T00:00:00Z" +} diff --git a/reports/current.md b/reports/current.md index 43451c7..0863a45 100644 --- a/reports/current.md +++ b/reports/current.md @@ -1,6 +1,6 @@ # NATS .NET Porting Status Report -Generated: 2026-02-27 09:49:21 UTC +Generated: 2026-02-27 09:50:38 UTC ## Modules (12 total) diff --git a/reports/report_810ef29.md b/reports/report_810ef29.md new file mode 100644 index 0000000..0863a45 --- /dev/null +++ b/reports/report_810ef29.md @@ -0,0 +1,35 @@ +# NATS .NET Porting Status Report + +Generated: 2026-02-27 09:50:38 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%)**