@wirecat/cli-base 0.61.3 → 0.62.0

package/CHANGELOG.md

@@ -8,6 +8,24 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.62.0 — 26.10.2026
+
+### Added
+
+- **`describeAlone(command, known)` describes a command as if it had no parent, reusing what `known` already holds.**
+  The shared-command check uses it to describe each command once per pass. Keep `known` for one pass only: a map kept
+  longer returns descriptions of commands that have since changed.
+
+### Fixed
+
+- **The shared-command check describes each command once per pass, not once for itself and again for every group
+  above it.** It runs when a shared command is built and before each command runs, so every command of every CLI paid
+  for it: about 60% of tg's setup, even for `tg --version`. On tg's real program one check now takes about 5 ms
+  instead of 11, building the program about 35 ms instead of 46, and a warm `run(["--version"])` about 30 ms instead
+  of 47 ([measurement](https://github.com/WireCatLabs/cli-testing/blob/main/performance/cli/shared-contract-check/README.md)).
+  The check still covers every protected subcommand, with the same errors and overrides, and `sharedContracts` returns
+  the same contracts as before.
+
 ## 0.61.3 — 26.10.2026
 
 ### Fixed

package/dist/commands/contracts.js

@@ -1,25 +1,22 @@
 import { isDeepStrictEqual } from "node:util";
 import { Command } from "commander";
 import { CliError } from "../errors.js";
-import { describeProgram } from "./registry.js";
+import { describeAlone } from "./registry.js";
 const protectedCommands = new WeakMap();
 export const hasSharedContract = (command) => protectedCommands.has(command);
-const snapshot = (command, children) => {
-    const root = new Command("contract");
-    const parent = command.parent;
-    root.addCommand(command);
-    const described = describeProgram(root)[0];
-    command.parent = parent;
-    if (!described)
+const hidden = (command) => Boolean(command._hidden);
+/** Shares arrays with the live command and with `known`: clone it before keeping it past the pass. */
+const snapshot = (command, known = new Map(), children) => {
+    if (hidden(command))
         throw new Error("a hidden command cannot own a shared contract");
-    const { commands: _, usage: __, path: ___, ...contract } = described;
-    return structuredClone({
+    const { commands: _, usage: __, path: ___, ...contract } = describeAlone(command, known);
+    return {
         ...contract,
         aliases: [...command.aliases()],
         children: (children ?? protectedCommands.get(command)?.originalChildren ?? command.commands)
-            .filter((child) => command.commands.includes(child) && !child._hidden)
+            .filter((child) => command.commands.includes(child) && !hidden(child))
             .map((child) => child.name()),
-    });
+    };
 };
 const same = isDeepStrictEqual;
 const visit = (root, fn) => {
@@ -36,11 +33,12 @@ const pathOf = (command) => {
 const differences = (before, after) => [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((field) => !same(before[field], after[field]));
 export const assertSharedContracts = (root) => {
     const changed = [];
+    const known = new Map();
     visit(root, (command) => {
         const protectedContract = protectedCommands.get(command);
         if (!protectedContract)
             return;
-        const fields = differences(protectedContract.contract, snapshot(command));
+        const fields = differences(protectedContract.contract, snapshot(command, known));
         if (fields.length)
             changed.push({ command: pathOf(command).join(" "), fields });
     });
@@ -55,9 +53,9 @@ export const overrideSharedContract = (command, reason, change) => {
     if (!protectedContract)
         throw new Error("only a core-owned command contract can be overridden");
     assertSharedContracts(command);
-    const before = snapshot(command);
+    const before = structuredClone(snapshot(command));
     change(command);
-    const after = snapshot(command);
+    const after = structuredClone(snapshot(command));
     const fields = differences(before, after);
     if (fields.length === 0)
         throw new Error("a shared contract override must change its named command");
@@ -119,14 +117,18 @@ export const sharedCommand = (factory) => (...args) => {
             if (!command.summary() && first.length > 80)
                 command.summary(`${first.slice(0, 77).replace(/\s+\S*$/, "")}…`);
         });
+        const known = new Map();
         visit(shared, (command) => {
-            if (!command._hidden && !protectedCommands.has(command))
-                protectedCommands.set(command, {
-                    contract: snapshot(command),
-                    reference: snapshot(command),
-                    overrides: [],
-                    originalChildren: [...command.commands],
-                });
+            if (hidden(command) || protectedCommands.has(command))
+                return;
+            // One object for both: `contract` is only ever replaced, and `reference` is cloned on the way out.
+            const contract = structuredClone(snapshot(command, known));
+            protectedCommands.set(command, {
+                contract,
+                reference: contract,
+                overrides: [],
+                originalChildren: [...command.commands],
+            });
         });
         shared.hook("preAction", () => {
             let root = shared;
@@ -147,6 +149,7 @@ export const customizeSharedCommand = (reference, reason, build, expectedOverrid
     const command = build();
     assertSharedContracts(command);
     const pending = [];
+    const known = new Map();
     const edits = [];
     const bindingPath = (own) => {
         const path = [own.name()];
@@ -163,7 +166,7 @@ export const customizeSharedCommand = (reference, reason, build, expectedOverrid
             return;
         if (!protectedCommands.has(own)) {
             const originalChildren = own.commands.filter((child) => inherited.reference.children.includes(child.name()));
-            const actual = snapshot(own, originalChildren);
+            const actual = structuredClone(snapshot(own, known, originalChildren));
             const overrides = differences(inherited.contract, actual).map((field) => ({
                 command: bindingPath(own),
                 field,

package/dist/commands/registry.d.ts

@@ -119,3 +119,8 @@ export declare const flatten: (commands: readonly CommandInfo[]) => CommandInfo[
  * in snake_case. Hand it to `stepOf` and `errorObjectOf` as `targets`.
  */
 export declare const stepTargets: (root: Command) => ((command: string) => StepTarget | undefined);
+/**
+ * The command as if it had no parent, so it inherits nothing, and its subcommands the same way. `known` holds what one
+ * pass has described already, so a whole tree costs one description per command; keep it no longer than that pass.
+ */
+export declare const describeAlone: (command: Command, known: Map<Command, CommandInfo>) => CommandInfo;

package/dist/commands/registry.js

@@ -40,7 +40,19 @@ export const stepTargets = (root) => {
         visit(child, [], root.options);
     return (command) => found.get(command);
 };
-const describe = (command, cli, parents, above) => {
+/**
+ * The command as if it had no parent, so it inherits nothing, and its subcommands the same way. `known` holds what one
+ * pass has described already, so a whole tree costs one description per command; keep it no longer than that pass.
+ */
+export const describeAlone = (command, known) => {
+    let found = known.get(command);
+    if (!found) {
+        found = describe(command, "", [], { offMcp: false, noOffline: false }, known);
+        known.set(command, found);
+    }
+    return found;
+};
+const describe = (command, cli, parents, above, known) => {
     const path = [...parents, command.name()];
     const args = command.registeredArguments.map(describeArgument);
     const options = describeOptions(command);
@@ -68,7 +80,7 @@ const describe = (command, cli, parents, above) => {
         ...(visible(command).length > 0 && hasAction(command) ? { runnable: true } : {}),
         arguments: args,
         options,
-        commands: visible(command).map((child) => describe(child, cli, path, here)),
+        commands: visible(command).map((child) => (known ? describeAlone(child, known) : describe(child, cli, path, here))),
     };
 };
 // Commander has no public getter for the action either; without one, a group prints its help.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.61.3",
+  "version": "0.62.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",