base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add invocation-owned Cobra sessions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-09 01:35:44 +00:00
parent 3ad355927c
commit a852301801
4 changed files with 179 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/roadmap/implementation.md
View File

@@ -1,6 +1,6 @@
# Performance implementation plan
Status: implementation in progress; Stages 1–7 are complete, Stages 8–11 have not started.
Status: implementation in progress; Stages 1–8 are complete, Stages 9–11 have not started.
Date: 2026-10-09.
@@ -615,7 +615,7 @@ with one tree allocation retained per app metadata generation.
## Stage 8: introduce an invocation-owned adapter session
**Status:** not started. **Prerequisite:** Stage 7.
**Status:** complete. **Prerequisite:** Stage 7.
**Files:** the adapter, its tests/benchmarks, and evidence. Root execution remains
functional through the existing package-level adapter helpers during this stage.
@@ -646,7 +646,30 @@ functional through the existing package-level adapter helpers during this stage.
**Completion:** the adapter can perform parsing and metadata presentation on
one prepared invocation tree while legacy root entry points still compile.
**Evidence:** pending.
**Evidence:** `GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none
GOSUMDB=off go test -mod=readonly -count=1 ./internal/cobra .` passed. Added
coverage for parse followed by help and usage on one session, fresh mutable
values and streams across separately prepared sessions, and neutral failures
for missing trees. Help output is captured and the selected command's original
streams are restored. Existing exact-path, parse-failure, and flag-state tests
continue to pass. The package-level helpers now each prepare one session and
delegate to its method.
Measurements used Go 1.26.8, linux/amd64, Linux 6.17.0-41-generic, Intel Core
i5-7260U CPU @ 2.20 GHz, based on source revision `3ad3559` with this stage's
changes in the working tree. The five-sample adapter command passed:
`GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off go test -mod=readonly -run '^$' -bench '^BenchmarkPerformance(Parse|SessionParseAndHelp)$' -benchmem -benchtime=200ms -count=5 ./internal/cobra`.
Raw output is in `/tmp/commandkit-performance-adapter-after-stage8.txt`.
The new parse-plus-help session benchmark, with an 8-sibling tree prepared
outside the timed loop, measured 33,456–50,352 ns/op, 10,658 B/op, and 226
allocations. The existing shallow/wide Parse wrapper measured 242,952–242,956
B/op and 1,706 allocations; deep measured 119,552–119,553 B/op and 827
allocations. Compared with the Stage 4 adapter baseline, each adds 16 bytes and
one allocation for the one-session wrapper. Timings ranged widely in this run,
so they are inconclusive; tree construction remains included in these wrapper
benchmarks. The session benchmark excludes its one-time tree preparation and
measures repeated parse plus help on the same fresh-per-session backend state.
## Stage 9: reuse the adapter session throughout root execution