zinkee 0.1.10 → 0.1.12

package/src/utils/argv-rewrite.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+
+import { commandRegistry } from "../command-registry.js";
+import { buildProgram } from "../program.js";
+import {
+  buildOptionMetadata,
+  hoistGlobalOptions,
+} from "./argv-rewrite.js";
+
+function rewrite(userArgs: readonly string[]): string[] {
+  const optionMeta = buildOptionMetadata(buildProgram());
+  return hoistGlobalOptions(["node", "zinkee", ...userArgs], optionMeta, commandRegistry);
+}
+
+describe("hoistGlobalOptions", () => {
+  it("moves boolean global flags before the subcommand path", () => {
+    expect(rewrite(["schemas", "list", "--json"])).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("moves global value flags together with their value", () => {
+    expect(rewrite(["schemas", "list", "--profile", "staging"])).toEqual([
+      "node",
+      "zinkee",
+      "--profile",
+      "staging",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("moves multiple globals preserving their relative order", () => {
+    expect(
+      rewrite(["schemas", "list", "--json", "--profile", "staging", "--read-only"]),
+    ).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "--profile",
+      "staging",
+      "--read-only",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("hoists globals that are interleaved between subcommand path tokens", () => {
+    expect(rewrite(["schemas", "--json", "fields", "create"])).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "fields",
+      "create",
+    ]);
+  });
+
+  it("does not touch global flags that already appear before the subcommand path", () => {
+    expect(rewrite(["--json", "schemas", "list"])).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("preserves --api-key when it appears after profiles add (subcommand-local option)", () => {
+    expect(
+      rewrite(["profiles", "add", "myProfile", "--api-key", "abc", "--base-url", "https://x"]),
+    ).toEqual([
+      "node",
+      "zinkee",
+      "profiles",
+      "add",
+      "myProfile",
+      "--api-key",
+      "abc",
+      "--base-url",
+      "https://x",
+    ]);
+  });
+
+  it("preserves --api-key/--base-url for profiles update while still hoisting other globals", () => {
+    expect(
+      rewrite(["profiles", "update", "myProfile", "--api-key", "abc", "--json"]),
+    ).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "profiles",
+      "update",
+      "myProfile",
+      "--api-key",
+      "abc",
+    ]);
+  });
+
+  it("supports the --foo=bar syntax for global value flags", () => {
+    expect(rewrite(["schemas", "list", "--profile=staging"])).toEqual([
+      "node",
+      "zinkee",
+      "--profile=staging",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("returns argv unchanged when no subcommand path is found", () => {
+    expect(rewrite(["--json"])).toEqual(["node", "zinkee", "--json"]);
+  });
+
+  it("respects -- and stops hoisting after it", () => {
+    expect(
+      rewrite(["schemas", "list", "--", "--json", "trailing"]),
+    ).toEqual([
+      "node",
+      "zinkee",
+      "schemas",
+      "list",
+      "--",
+      "--json",
+      "trailing",
+    ]);
+  });
+});
+
+describe("buildOptionMetadata", () => {
+  it("registers local options for leaf subcommands", () => {
+    const optionMeta = buildOptionMetadata(buildProgram());
+    const profilesAdd = optionMeta.localOptionsByCommand.get("profiles add");
+
+    expect(profilesAdd?.has("--api-key")).toBe(true);
+    expect(profilesAdd?.has("--base-url")).toBe(true);
+  });
+
+  it("recognises global value vs boolean flags", () => {
+    const optionMeta = buildOptionMetadata(buildProgram());
+
+    expect(optionMeta.valueFlags.has("--profile")).toBe(true);
+    expect(optionMeta.booleanFlags.has("--json")).toBe(true);
+    expect(optionMeta.booleanFlags.has("--read-only")).toBe(true);
+  });
+});

package/src/utils/argv-rewrite.ts

@@ -0,0 +1,269 @@
+import type { Command } from "commander";
+
+export const HOISTABLE_GLOBAL_FLAGS = {
+  "--profile": "value",
+  "--base-url": "value",
+  "--api-key": "value",
+  "--read-only": "boolean",
+  "--json": "boolean",
+} as const satisfies Record<string, "value" | "boolean">;
+
+type HoistableFlagName = keyof typeof HOISTABLE_GLOBAL_FLAGS;
+
+function isHoistableFlag(flagName: string): flagName is HoistableFlagName {
+  return Object.hasOwn(HOISTABLE_GLOBAL_FLAGS, flagName);
+}
+
+export interface OptionMetadata {
+  valueFlags: Set<string>;
+  booleanFlags: Set<string>;
+  localOptionsByCommand: Map<string, Set<string>>;
+}
+
+function getCommandPath(command: Command): string {
+  const parts: string[] = [];
+  let cursor: Command | null = command;
+  while (cursor && cursor.parent) {
+    parts.unshift(cursor.name());
+    cursor = cursor.parent;
+  }
+  return parts.join(" ");
+}
+
+export function buildOptionMetadata(program: Command): OptionMetadata {
+  const valueFlags = new Set<string>();
+  const booleanFlags = new Set<string>();
+  const localOptionsByCommand = new Map<string, Set<string>>();
+
+  function visit(command: Command, isRoot: boolean): void {
+    const localFlags = new Set<string>();
+
+    for (const option of command.options) {
+      if (!option.long) continue;
+
+      if (option.required || option.optional) {
+        valueFlags.add(option.long);
+      } else {
+        booleanFlags.add(option.long);
+      }
+
+      if (!isRoot) {
+        localFlags.add(option.long);
+      }
+    }
+
+    if (!isRoot) {
+      localOptionsByCommand.set(getCommandPath(command), localFlags);
+    }
+
+    for (const sub of command.commands) {
+      visit(sub, false);
+    }
+  }
+
+  visit(program, true);
+  return { valueFlags, booleanFlags, localOptionsByCommand };
+}
+
+export function createDefaultOptionMetadata(): OptionMetadata {
+  return {
+    valueFlags: new Set([
+      "--profile",
+      "--base-url",
+      "--api-key",
+      "--install-completion",
+      "--show-completion",
+    ]),
+    booleanFlags: new Set([
+      "--read-only",
+      "--json",
+      "--example",
+      "--help",
+    ]),
+    localOptionsByCommand: new Map(),
+  };
+}
+
+interface FlagSplit {
+  flagName: string;
+  inlineValue: string | undefined;
+}
+
+function isFlagToken(token: string): boolean {
+  return token.length > 1 && token.startsWith("-");
+}
+
+function splitFlagToken(token: string): FlagSplit {
+  if (token.startsWith("--") && token.includes("=")) {
+    const eqIdx = token.indexOf("=");
+    return {
+      flagName: token.slice(0, eqIdx),
+      inlineValue: token.slice(eqIdx + 1),
+    };
+  }
+  return { flagName: token, inlineValue: undefined };
+}
+
+function flagConsumesValue(flagName: string, optionMeta: OptionMetadata): boolean {
+  if (optionMeta.valueFlags.has(flagName)) {
+    return true;
+  }
+  if (optionMeta.booleanFlags.has(flagName)) {
+    return false;
+  }
+  return true;
+}
+
+interface OperandPosition {
+  index: number;
+  token: string;
+}
+
+export function collectOperandTokens(
+  userArgs: readonly string[],
+  optionMeta: OptionMetadata,
+  options: { skipFlag?: string } = {},
+): OperandPosition[] {
+  const operands: OperandPosition[] = [];
+  let i = 0;
+  while (i < userArgs.length) {
+    const token = userArgs[i] as string;
+
+    if (token === "--") {
+      break;
+    }
+
+    if (isFlagToken(token)) {
+      const { flagName, inlineValue } = splitFlagToken(token);
+
+      if (options.skipFlag !== undefined && flagName === options.skipFlag) {
+        i += 1;
+        continue;
+      }
+
+      if (inlineValue !== undefined) {
+        i += 1;
+        continue;
+      }
+
+      const consumes = flagConsumesValue(flagName, optionMeta);
+      const next = userArgs[i + 1];
+      if (consumes && next !== undefined && !isFlagToken(next)) {
+        i += 2;
+      } else {
+        i += 1;
+      }
+      continue;
+    }
+
+    operands.push({ index: i, token });
+    i += 1;
+  }
+  return operands;
+}
+
+export interface CommandPathMatch {
+  commandName: string;
+  firstArgvIndex: number;
+  lastArgvIndex: number;
+}
+
+export function findCommandPath(
+  operands: readonly OperandPosition[],
+  registry: Record<string, unknown>,
+): CommandPathMatch | null {
+  if (operands.length === 0) return null;
+
+  const commandsByLength = Object.keys(registry).sort(
+    (left, right) => right.split(" ").length - left.split(" ").length,
+  );
+
+  for (let start = 0; start < operands.length; start += 1) {
+    for (const commandName of commandsByLength) {
+      const parts = commandName.split(" ");
+      if (start + parts.length > operands.length) continue;
+
+      let matches = true;
+      for (let j = 0; j < parts.length; j += 1) {
+        if (operands[start + j]!.token !== parts[j]) {
+          matches = false;
+          break;
+        }
+      }
+
+      if (matches) {
+        return {
+          commandName,
+          firstArgvIndex: operands[start]!.index,
+          lastArgvIndex: operands[start + parts.length - 1]!.index,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+export function hoistGlobalOptions(
+  argv: readonly string[],
+  optionMeta: OptionMetadata,
+  registry: Record<string, unknown>,
+): string[] {
+  if (argv.length < 3) return [...argv];
+
+  const userArgs = argv.slice(2);
+  const operands = collectOperandTokens(userArgs, optionMeta);
+  const cmdPath = findCommandPath(operands, registry);
+
+  if (!cmdPath) return [...argv];
+
+  const localOptions =
+    optionMeta.localOptionsByCommand.get(cmdPath.commandName) ?? new Set<string>();
+
+  const hoisted: string[] = [];
+  const remaining: string[] = [];
+  let i = 0;
+
+  while (i < userArgs.length) {
+    const token = userArgs[i] as string;
+
+    if (token === "--") {
+      remaining.push(...userArgs.slice(i));
+      break;
+    }
+
+    if (!isFlagToken(token)) {
+      remaining.push(token);
+      i += 1;
+      continue;
+    }
+
+    const { flagName, inlineValue } = splitFlagToken(token);
+
+    if (!isHoistableFlag(flagName)) {
+      remaining.push(token);
+      i += 1;
+      continue;
+    }
+
+    const isAfterCommandPath = i > cmdPath.lastArgvIndex;
+    const collidesWithLocal = localOptions.has(flagName);
+
+    const target = isAfterCommandPath && collidesWithLocal ? remaining : hoisted;
+    target.push(token);
+
+    const spec = HOISTABLE_GLOBAL_FLAGS[flagName];
+    if (spec === "value" && inlineValue === undefined) {
+      const next = userArgs[i + 1];
+      if (next !== undefined && !isFlagToken(next)) {
+        target.push(next);
+        i += 2;
+        continue;
+      }
+    }
+
+    i += 1;
+  }
+
+  return [argv[0] as string, argv[1] as string, ...hoisted, ...remaining];
+}