From c2059039003e55069d1007d9101186c9c48dcffa Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 3 Nov 2026 12:54:34 +0000 Subject: [PATCH] Record shell completion efficiency findings --- docs/roadmap/remediation.md | 52 ++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 5da5724..2f9d68b 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -1,6 +1,6 @@ # Shell completion audit remediation -Status: six findings open. The completed invocation reporting audit is retained +Status: six fixes open; two efficiency findings for consideration. The completed invocation reporting audit is retained below as historical evidence. ## Completion review scope @@ -143,6 +143,56 @@ kinds and existing execution behavior; the hint must not become an allowlist. Cover the canonical command and the maintained alias without starting a smoke test or loading an engine for completion. +## Completion algorithmic review + +Reviewed the installed metadata, route selection, flag and operand walk, +candidate construction, and reply encoding by source inspection. The flag walk +advances through the input rather than rescanning earlier tokens. Operand +allocation is linear in the number of bindings, and choice filtering and reply +encoding are linear in the candidates and text they inspect or emit. Stage 4 +expressly requires checking each suggested child against ordinary alias routing; +this review does not propose removing or replacing that check. No additional +correctness defect or newly introduced quadratic algorithm was identified within +the remaining scope. The six existing findings remain open. + +### 7. Look up canonical completion metadata without scanning siblings + +Priority: P3. Status: for consideration. + +[completionCommand](../../completion_context.go) searches the metadata child +slice at every component of an already resolved canonical path. For depth +`D` and sibling counts `B_i` at those levels, the lookup can take +`O(sum(B_i))` name comparisons. Even querying a single selected leaf in a wide +group can scan every sibling, after routing already found the canonical path. +This is distinct from enumerating child suggestions, where visiting children +can be necessary. + +Consider indexing neutral metadata by canonical path or associating the +metadata with the existing canonical nodes when building the snapshot. A +name-indexed walk then takes expected `O(D)` map lookups. Building and storing +a separate index would cost `O(N)` entries for `N` installed nodes; prefer +reusing existing tree storage where practical. Preserve registration snapshot +refresh and the selected candidate insertion checks. + +### 8. Avoid sorting resolved flag aliases on every completion query + +Priority: P3. Status: for consideration. + +[resolveCompletionContext](../../completion_context.go) calls +[neutralRecords](../../flag_aliases.go) for the selected canonical or discovery +context. For `A` resolved aliases, this builds and sorts a key slice in +`O(A log A)` comparisons, then builds a record slice. The completion flag +walker immediately indexes those records by spelling. Source spellings are +already unique in this resolved context, so sorted input contributes neither +precedence nor candidate ordering to the lookup. + +Build completion's lookup from the resolved mappings in expected `O(A)` +time, or reuse a snapshot-owned lookup if that avoids duplicate allocation +without complicating installation. Preserve existing sorted records where +display order matters and preserve scoped precedence and target availability. +This is a source-level opportunity; no latency or allocation threshold is +proposed. + --- ## Historical invocation reporting audit remediation