From 97be7a25a21dbc47d7b55e79601af6c2f5dc5574 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 27 Feb 2026 04:34:52 -0500 Subject: [PATCH] docs: add PortTracker batch operations design Design for batch-update and batch-map subcommands across all entity types (feature, test, module, library) with shared filter infrastructure and dry-run-by-default safety. --- .../2026-02-27-porttracker-batch-design.md | 120 ++++++++++++++++++ reports/current.md | 2 +- reports/report_11ec33d.md | 35 +++++ 3 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 docs/plans/2026-02-27-porttracker-batch-design.md create mode 100644 reports/report_11ec33d.md diff --git a/docs/plans/2026-02-27-porttracker-batch-design.md b/docs/plans/2026-02-27-porttracker-batch-design.md new file mode 100644 index 0000000..914350f --- /dev/null +++ b/docs/plans/2026-02-27-porttracker-batch-design.md @@ -0,0 +1,120 @@ +# PortTracker Batch Operations Design + +**Date:** 2026-02-27 +**Status:** Approved + +## Problem + +The PortTracker CLI only supports one-at-a-time operations for status updates, mappings, and N/A marking. With ~3700 features and ~3300 tests, bulk operations require dropping to raw `sqlite3` commands. This is error-prone and bypasses any validation the CLI could provide. + +## Design + +### Approach + +Add `batch-update` and `batch-map` subcommands under each existing entity command (`feature`, `test`, `module`, `library`). All batch commands share a common filter + dry-run infrastructure. + +### Shared Batch Infrastructure + +A new `BatchFilters` static class in `Commands/BatchFilters.cs` provides: + +**Filter Options** (combined with AND logic): +- `--ids ` — ID range like `100-200`, comma-separated `1,5,10`, or mixed `1-5,10,20-25` +- `--module ` — filter by module_id (feature/test only) +- `--status ` — filter by current status value + +**Dry-Run Default:** +- Without `--execute`, commands show a preview: "Would affect N items:" + table of matching rows +- With `--execute`, changes are applied inside a transaction and "Updated N items." is printed +- At least one filter is required (no accidental "update everything" with zero filters) + +**Shared Methods:** +- `AddFilterOptions(Command cmd, bool includeModuleFilter)` — adds the common options to a command +- `BuildWhereClause(...)` — returns SQL WHERE clause + parameters from parsed filter values +- `PreviewOrExecute(Database db, string table, string selectSql, string updateSql, params[], bool execute)` — handles dry-run preview vs actual execution + +### Feature Batch Commands + +**`feature batch-update`** +- Filters: `--ids`, `--module`, `--status` +- Setters: `--set-status` (required), `--set-notes` (optional) +- Flag: `--execute` + +**`feature batch-map`** +- Filters: `--ids`, `--module`, `--status` +- Setters: `--set-project`, `--set-class`, `--set-method` (at least one required) +- Flag: `--execute` + +### Test Batch Commands + +**`test batch-update`** +- Filters: `--ids`, `--module`, `--status` +- Setters: `--set-status` (required), `--set-notes` (optional) +- Flag: `--execute` + +**`test batch-map`** +- Filters: `--ids`, `--module`, `--status` +- Setters: `--set-project`, `--set-class`, `--set-method` (at least one required) +- Flag: `--execute` + +### Module Batch Commands + +**`module batch-update`** +- Filters: `--ids`, `--status` +- Setters: `--set-status` (required), `--set-notes` (optional) +- Flag: `--execute` + +**`module batch-map`** +- Filters: `--ids`, `--status` +- Setters: `--set-project`, `--set-namespace`, `--set-class` (at least one required) +- Flag: `--execute` + +### Library Batch Commands + +**`library batch-update`** +- Filters: `--ids`, `--status` +- Setters: `--set-status` (required), `--set-notes` (optional, maps to `dotnet_usage_notes`) +- Flag: `--execute` + +**`library batch-map`** +- Filters: `--ids`, `--status` +- Setters: `--set-package`, `--set-namespace`, `--set-notes` (at least one required) +- Flag: `--execute` + +## Examples + +```bash +# Preview: which features in module 5 are not_started? +porttracker feature batch-update --module 5 --status not_started --set-status deferred + +# Execute: defer all features in module 5 with a reason +porttracker feature batch-update --module 5 --status not_started --set-status deferred --set-notes "needs server runtime" --execute + +# Execute: mark tests 500-750 as deferred +porttracker test batch-update --ids 500-750 --set-status deferred --set-notes "server-integration" --execute + +# Execute: batch-map all features in module 3 to a .NET project +porttracker feature batch-map --module 3 --set-project "ZB.MOM.NatsNet.Server" --execute + +# Preview: what libraries are unmapped? +porttracker library batch-update --status not_mapped --set-status mapped + +# Execute: batch-map libraries +porttracker library batch-map --ids 1-20 --set-package "Microsoft.Extensions.Logging" --set-namespace "Microsoft.Extensions.Logging" --execute +``` + +## File Changes + +| File | Change | +|------|--------| +| `Commands/BatchFilters.cs` | New — shared filter options, WHERE builder, preview/execute logic | +| `Commands/FeatureCommands.cs` | Add `batch-update` and `batch-map` subcommands | +| `Commands/TestCommands.cs` | Add `batch-update` and `batch-map` subcommands | +| `Commands/ModuleCommands.cs` | Add `batch-update` and `batch-map` subcommands | +| `Commands/LibraryCommands.cs` | Add `batch-update` and `batch-map` subcommands | +| `Data/Database.cs` | Add `ExecuteInTransaction` helper for batch safety | + +## Non-Goals + +- No batch create or batch delete — not needed for the porting workflow +- No raw `--where` SQL escape hatch — structured filters cover all use cases +- No interactive y/n prompts — dry-run + `--execute` flag is sufficient and scriptable diff --git a/reports/current.md b/reports/current.md index d197318..5989d9d 100644 --- a/reports/current.md +++ b/reports/current.md @@ -1,6 +1,6 @@ # NATS .NET Porting Status Report -Generated: 2026-02-27 02:53:53 UTC +Generated: 2026-02-27 09:34:53 UTC ## Modules (12 total) diff --git a/reports/report_11ec33d.md b/reports/report_11ec33d.md new file mode 100644 index 0000000..5989d9d --- /dev/null +++ b/reports/report_11ec33d.md @@ -0,0 +1,35 @@ +# NATS .NET Porting Status Report + +Generated: 2026-02-27 09:34:53 UTC + +## Modules (12 total) + +| Status | Count | +|--------|-------| +| verified | 12 | + +## Features (3673 total) + +| Status | Count | +|--------|-------| +| deferred | 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%)**