@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/completion/templates/fish.ts

@@ -0,0 +1,245 @@
+/**
+ * The fish completion script (static tier). Requires fish >= 3.
+ *
+ * Declarative: one `complete -c` rule per fact, gated by the
+ * `__<bin>_at <noun> [verb]` position probe. Default file completion is
+ * suppressed (`-f`); enum values are inlined literals; file params force
+ * native files back on (`-rF`); only `{kind:"names"}` contexts exec the CLI
+ * via a command substitution — fish treats substitution results as literal
+ * candidates (split on newlines, never evaluated). Each name rule ANDs a
+ * `__<bin>_minchars` guard into its condition, so the exec waits for `minChars`
+ * typed chars. No `eval`, no backticks.
+ *
+ * Static-tier coarseness (the resolver is exact): positional value rules are
+ * not index-gated, and a mixed self-verb + sub-verb noun only offers its
+ * sub-verbs — `__complete` answers both cases precisely.
+ */
+
+import type { CompletionModel, FlagEntry, VerbEntry } from "../types.js";
+import { globalValueFlags, nounNames, verbViews, wordList } from "./shared.js";
+
+/** A shell-safe function-name base for the bin (`pragma` -> `__pragma`). */
+function fnBase(binName: string): string {
+  return `__${binName.replace(/[^A-Za-z0-9_]/g, "_")}`;
+}
+
+/** AND a `minChars` guard into a name rule's condition (or start one). */
+function withMinChars(
+  fn: string,
+  condition: string | undefined,
+  minChars: number,
+): string | undefined {
+  if (minChars <= 0) return condition;
+  const guard = `${fn}_minchars ${minChars}`;
+  return condition ? `${condition}; and ${guard}` : guard;
+}
+
+/** The rule fragment completing one flag of a view (or a global flag). */
+function flagRule(
+  binName: string,
+  fn: string,
+  condition: string | undefined,
+  flag: FlagEntry,
+  minChars: number,
+): string {
+  const name = flag.flag.replace(/^--/, "");
+  // A name-source value gates its exec on `minChars`; other rules keep the bare
+  // position condition (enum/file/none complete on bare TAB).
+  const cond =
+    flag.takesValue && flag.source.kind === "names"
+      ? withMinChars(fn, condition, minChars)
+      : condition;
+  const parts = [`complete -c ${binName}`];
+  if (cond) parts.push(`-n "${cond}"`);
+  parts.push(`-l ${name}`);
+  if (flag.takesValue) {
+    switch (flag.source.kind) {
+      case "values":
+        parts.push(`-x -a "${wordList(flag.source.values, "fish values")}"`);
+        break;
+      case "files":
+        parts.push("-rF");
+        break;
+      case "names":
+        parts.push(
+          `-x -a "(${binName} __complete -- (${fn}_words) 2>/dev/null)"`,
+        );
+        break;
+      case "none":
+        parts.push("-x");
+        break;
+    }
+  }
+  return parts.join(" ");
+}
+
+/** The positional value rule for a view, or undefined when it offers nothing. */
+function positionalRule(
+  binName: string,
+  fn: string,
+  condition: string,
+  verb: VerbEntry,
+  minChars: number,
+): string | undefined {
+  // fish rules are not index-gated; offer the union of the verb's positional
+  // sources (a name source delegates to the resolver, which IS index-exact).
+  const values = new Set<string>();
+  let names = false;
+  let files = false;
+  for (const positional of verb.positionals) {
+    if (positional.source.kind === "values") {
+      for (const value of positional.source.values) values.add(value);
+    }
+    if (positional.source.kind === "names") names = true;
+    if (positional.source.kind === "files") files = true;
+  }
+  // A name source gates its exec on `minChars`; a values/files positional keeps
+  // the bare position condition so it still completes on bare TAB.
+  const cond = names ? withMinChars(fn, condition, minChars) : condition;
+  const parts = [`complete -c ${binName} -n "${cond}"`];
+  if (names) {
+    parts.push(`-a "(${binName} __complete -- (${fn}_words) 2>/dev/null)"`);
+  } else if (values.size > 0) {
+    parts.push(
+      `-a "${wordList([...values].sort(), "fish positional values")}"`,
+    );
+  } else if (files) {
+    parts.push("-F");
+  } else {
+    return undefined;
+  }
+  return parts.join(" ");
+}
+
+/**
+ * Render the fish completion script.
+ *
+ * @param model - The completion model.
+ * @param binName - The binary to complete (function names derive from it).
+ * @param minChars - Minimum typed chars before a name source execs `__complete`.
+ * @returns The script text.
+ */
+export function fishScript(
+  model: CompletionModel,
+  binName: string,
+  minChars: number,
+): string {
+  const fn = fnBase(binName);
+  const globalValueSkips = wordList(
+    globalValueFlags(model).map((flag) => flag.flag),
+    "fish global value flags",
+  );
+
+  const lines: string[] = [
+    `# ${binName} fish completion (static tier) — generated by \`${binName} setup completions\`. Do not edit.`,
+    "# Structure (nouns, verbs, flags, enum values) is inlined and never execs;",
+    `# name arguments call \`${binName} __complete\` (storeless, never-throw) once`,
+    `# ${minChars} chars are typed; file arguments use native completion (-rF). Requires fish >= 3.`,
+    `function ${fn}_words`,
+    "    set -l toks (commandline -opc)",
+    "    set -l cur (commandline -ct)",
+    "    printf '%s\\n' $toks[2..-1] $cur",
+    "end",
+    ...(minChars > 0
+      ? [
+          `function ${fn}_minchars`,
+          "    test (string length -- (commandline -ct)) -ge $argv[1]",
+          "end",
+        ]
+      : []),
+    `function ${fn}_at`,
+    "    set -l cmd (commandline -opc)",
+    "    set -l noun ''",
+    "    set -l verb ''",
+    "    set -l skip 0",
+    "    for w in $cmd[2..-1]",
+    "        if test $skip -eq 1",
+    "            set skip 0",
+    "            continue",
+    "        end",
+    "        switch $w",
+    `            case ${globalValueSkips}`,
+    "                set skip 1",
+    "            case '-*'",
+    "            case '*'",
+    '                if test -z "$noun"',
+    "                    set noun $w",
+    '                else if test -z "$verb"',
+    "                    set verb $w",
+    "                end",
+    "        end",
+    "    end",
+    '    test "$noun" = "$argv[1]"; and test "$verb" = "$argv[2]"',
+    "end",
+    `complete -c ${binName} -f`,
+    "",
+    "# nouns",
+    `complete -c ${binName} -n "${fn}_at ''" -a "${wordList(nounNames(model), "fish nouns")}"`,
+    "",
+    "# global flags",
+    ...model.globalFlags.map((flag) =>
+      flagRule(
+        binName,
+        fn,
+        flag.rootOnly === true ? `${fn}_at ''` : undefined,
+        flag,
+        minChars,
+      ),
+    ),
+  ];
+
+  for (const entry of model.nouns) {
+    if (entry.verbs.length > 0) {
+      lines.push(
+        "",
+        `# ${entry.noun} verbs`,
+        `complete -c ${binName} -n "${fn}_at ${entry.noun}" -a "${wordList(
+          entry.verbs.map((verb) => verb.label),
+          "fish verbs",
+        )}"`,
+      );
+    }
+  }
+
+  for (const view of verbViews(model)) {
+    // A mixed noun's self-verb state is not expressible with the probe; its
+    // sub-verbs own the second word and the resolver owns the rest.
+    if (
+      view.self &&
+      view.verb.positionals.length === 0 &&
+      view.verb.flags.length === 0 &&
+      !view.verb.mutates
+    ) {
+      continue;
+    }
+    const nounEntry = model.nouns.find((entry) => entry.noun === view.noun);
+    if (view.self && (nounEntry?.verbs.length ?? 0) > 0) continue;
+
+    const condition = view.self
+      ? `${fn}_at ${view.noun}`
+      : `${fn}_at ${view.noun} ${view.verb.label}`;
+    const rules: string[] = [];
+    for (const flag of view.verb.flags) {
+      rules.push(flagRule(binName, fn, condition, flag, minChars));
+    }
+    if (view.verb.mutates) {
+      for (const flag of model.mutationFlags) {
+        rules.push(flagRule(binName, fn, condition, flag, minChars));
+      }
+    }
+    const positional = positionalRule(
+      binName,
+      fn,
+      condition,
+      view.verb,
+      minChars,
+    );
+    if (positional) rules.push(positional);
+    if (rules.length > 0) {
+      lines.push("", `# ${view.key}`, ...rules);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}

package/src/kernel/completion/templates/shared.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared rendering helpers for the static shell-completion templates.
+ *
+ * Everything a template interpolates flows through here: tokens are
+ * re-asserted against the safety allowlist at emit time (belt-and-braces on
+ * top of the model-build gate), and the per-(noun,verb) views give each shell
+ * the same case-table data, so the three scripts can never disagree about
+ * structure. All lists are derived from the model — the templates contain no
+ * live names of their own.
+ */
+
+import { assertSafeToken } from "../model.js";
+import type {
+  CompletionModel,
+  FlagEntry,
+  NounEntry,
+  VerbEntry,
+} from "../types.js";
+
+export { assertSafeToken } from "../model.js";
+
+/** One (noun, verb) pair a script addresses — self-verbs have key `noun/`. */
+export interface VerbView {
+  /** The noun token. */
+  readonly noun: string;
+  /** The verb entry (the noun's self-verb when `self`). */
+  readonly verb: VerbEntry;
+  /** Whether this is the noun's self-verb (bare invocation). */
+  readonly self: boolean;
+  /** The case-table key: `noun/label` for sub-verbs, `noun/` for self. */
+  readonly key: string;
+  /** Non-flag words before the first positional (1 self, 2 sub). */
+  readonly skipWords: 1 | 2;
+}
+
+/**
+ * Every verb view of the model, in deterministic order (nouns sorted, each
+ * noun's self-verb first, then its sub-verbs sorted).
+ */
+export function verbViews(model: CompletionModel): VerbView[] {
+  const views: VerbView[] = [];
+  for (const entry of model.nouns) {
+    if (entry.selfVerb) {
+      views.push({
+        noun: entry.noun,
+        verb: entry.selfVerb,
+        self: true,
+        key: `${entry.noun}/`,
+        skipWords: 1,
+      });
+    }
+    for (const verb of entry.verbs) {
+      views.push({
+        noun: entry.noun,
+        verb,
+        self: false,
+        key: `${entry.noun}/${verb.label}`,
+        skipWords: 2,
+      });
+    }
+  }
+  return views;
+}
+
+/**
+ * Join already-validated tokens into a script word list, re-asserting each
+ * (flags are validated on their bare name — the dashes are ours).
+ *
+ * @param tokens - The tokens to inline.
+ * @param where - Human-readable location for the throw message.
+ * @returns The space-joined list, safe to place inside double quotes.
+ * @throws Error when any token fails the allowlist.
+ */
+export function wordList(tokens: readonly string[], where: string): string {
+  for (const token of tokens) {
+    assertSafeToken(token.replace(/^--?/, ""), where);
+  }
+  return tokens.join(" ");
+}
+
+/** The noun tokens offered at the root. */
+export function nounNames(model: CompletionModel): string[] {
+  return model.nouns.map((entry: NounEntry) => entry.noun);
+}
+
+/** Global flag names offered at the root (includes `rootOnly`). */
+export function rootFlagNames(model: CompletionModel): string[] {
+  return model.globalFlags.map((flag) => flag.flag);
+}
+
+/** Global flag names offered after a noun (excludes `rootOnly`). */
+export function globalFlagNames(model: CompletionModel): string[] {
+  return model.globalFlags
+    .filter((flag) => flag.rootOnly !== true)
+    .map((flag) => flag.flag);
+}
+
+/** Global flags that take a value (their values are inlined per shell). */
+export function globalValueFlags(model: CompletionModel): FlagEntry[] {
+  return model.globalFlags.filter((flag) => flag.takesValue);
+}
+
+/** The flag names a view offers: verb + mutation (iff mutates) + globals. */
+export function offeredFlagNames(
+  model: CompletionModel,
+  view: VerbView,
+): string[] {
+  return [
+    ...view.verb.flags.map((flag) => flag.flag),
+    ...(view.verb.mutates ? model.mutationFlags.map((flag) => flag.flag) : []),
+    ...globalFlagNames(model),
+  ];
+}
+
+/**
+ * Every value-taking flag in scope for a view (verb + globals) — the flags
+ * whose values a positional-index scan must skip.
+ */
+export function valueFlagNames(
+  model: CompletionModel,
+  view: VerbView,
+): string[] {
+  return [
+    ...view.verb.flags
+      .filter((flag) => flag.takesValue)
+      .map((flag) => flag.flag),
+    ...globalValueFlags(model).map((flag) => flag.flag),
+  ];
+}
+
+/** Whether a view has any flag of its own to name (beyond the globals). */
+export function hasOwnFlags(view: VerbView): boolean {
+  return view.verb.flags.length > 0 || view.verb.mutates;
+}

package/src/kernel/completion/templates/zsh.ts

@@ -0,0 +1,246 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: zsh parameter expansions, not JS templates
+/**
+ * The zsh completion script (static tier). Requires zsh >= 5.
+ *
+ * Deliberately a `compadd`-table script, NOT `_arguments` — `_arguments`
+ * would interpolate param docs into its spec strings, an injection surface
+ * the grammar must never open. Structure is inlined as literal `compadd --`
+ * arguments (the `--` guard keeps dash-leading candidates data); files go
+ * through `_files`; only `{kind:"names"}` contexts exec the CLI, ingesting
+ * `pragma __complete` output via the newline-split `${(f)...}` expansion —
+ * candidates are never word-split or evaluated. That exec is gated by
+ * `minChars`. No `eval`, no backticks.
+ */
+
+import type { CompletionModel, CompletionSource } from "../types.js";
+import {
+  globalFlagNames,
+  globalValueFlags,
+  hasOwnFlags,
+  nounNames,
+  offeredFlagNames,
+  rootFlagNames,
+  type VerbView,
+  valueFlagNames,
+  verbViews,
+  wordList,
+} from "./shared.js";
+
+/** A shell-safe function-name base for the bin (`pragma` -> `_pragma`). */
+function fnBase(binName: string): string {
+  return `_${binName.replace(/[^A-Za-z0-9_]/g, "_")}`;
+}
+
+/** The zsh action completing a value source, or undefined for `none`. */
+function sourceAction(
+  source: CompletionSource,
+  fn: string,
+): string | undefined {
+  switch (source.kind) {
+    case "values":
+      return `compadd -- ${wordList(source.values, "zsh values")}`;
+    case "files":
+      return "_files";
+    case "names":
+      return `${fn}_dynamic`;
+    case "none":
+      return undefined;
+  }
+}
+
+/** The `noun/verb/--flag` case arms answering flag-value contexts. */
+function flagValueArms(model: CompletionModel, fn: string): string[] {
+  const arms: string[] = [];
+  for (const view of verbViews(model)) {
+    for (const flag of view.verb.flags) {
+      if (!flag.takesValue) continue;
+      const action = sourceAction(flag.source, fn);
+      arms.push(
+        `    ${view.key}/${flag.flag}) ${action === undefined ? "return 0" : `${action}; return 0`} ;;`,
+      );
+    }
+  }
+  return arms;
+}
+
+/** The global `--flag` case arms (e.g. --format, --detail values). */
+function globalValueArms(model: CompletionModel, fn: string): string[] {
+  return globalValueFlags(model).flatMap((flag) => {
+    const action = sourceAction(flag.source, fn);
+    return action === undefined
+      ? []
+      : [`    ${flag.flag}) ${action}; return 0 ;;`];
+  });
+}
+
+/** The `noun/verb` case arms offering per-verb flag names. */
+function flagNameArms(model: CompletionModel): string[] {
+  return verbViews(model)
+    .filter(hasOwnFlags)
+    .map(
+      (view) =>
+        `      ${view.key}) compadd -- ${wordList(offeredFlagNames(model, view), "zsh flags")}; return 0 ;;`,
+    );
+}
+
+/** The `noun` case arms offering sub-verb labels. */
+function verbArms(model: CompletionModel): string[] {
+  return model.nouns
+    .filter((entry) => entry.verbs.length > 0)
+    .map(
+      (entry) =>
+        `      ${entry.noun}) compadd -- ${wordList(
+          entry.verbs.map((verb) => verb.label),
+          "zsh verbs",
+        )}; return 0 ;;`,
+    );
+}
+
+/** The positional case arm for one view, or undefined when it offers nothing. */
+function positionalArm(
+  model: CompletionModel,
+  view: VerbView,
+  fn: string,
+): string | undefined {
+  const slots: string[] = [];
+  view.verb.positionals.forEach((positional, index) => {
+    const action = sourceAction(positional.source, fn);
+    if (action === undefined) return;
+    const last = index === view.verb.positionals.length - 1;
+    const pattern = positional.variadic && last ? "*" : String(index);
+    slots.push(`        ${pattern}) ${action} ;;`);
+  });
+  if (slots.length === 0) return undefined;
+  return [
+    `    ${view.key})`,
+    `      ${fn}_pos ${view.skipWords} "${wordList(valueFlagNames(model, view), "zsh value flags")}"`,
+    '      case "$POS" in',
+    ...slots,
+    "      esac",
+    "      ;;",
+  ].join("\n");
+}
+
+/** Wrap case arms in a `case` statement, or nothing when there are no arms. */
+function caseBlock(
+  subject: string,
+  arms: readonly string[],
+  indent: string,
+): string[] {
+  if (arms.length === 0) return [];
+  return [`${indent}case ${subject} in`, ...arms, `${indent}esac`];
+}
+
+/**
+ * Render the zsh completion script.
+ *
+ * @param model - The completion model.
+ * @param binName - The binary to complete (function names derive from it).
+ * @param minChars - Minimum typed chars before a name source execs `__complete`.
+ * @returns The script text.
+ */
+export function zshScript(
+  model: CompletionModel,
+  binName: string,
+  minChars: number,
+): string {
+  const fn = fnBase(binName);
+  const positionalArms = verbViews(model).flatMap((view) => {
+    const arm = positionalArm(model, view, fn);
+    return arm === undefined ? [] : [arm];
+  });
+  const globalValueSkips = globalValueFlags(model)
+    .map((flag) => flag.flag)
+    .join("|");
+  const verbSection =
+    verbArms(model).length === 0
+      ? []
+      : [
+          "",
+          "  # verbs",
+          '  if [[ -z "$verb" ]]; then',
+          ...caseBlock('"$noun"', verbArms(model), "    "),
+          "  fi",
+        ];
+
+  const lines = [
+    `#compdef ${binName}`,
+    `# ${binName} zsh completion (static tier) — generated by \`${binName} setup completions\`. Do not edit.`,
+    "# Structure (nouns, verbs, flags, enum values) is inlined and never execs;",
+    `# entity arguments call \`${binName} __complete\` (storeless, never-throw);`,
+    "# file arguments use _files. Requires zsh >= 5.",
+    `${fn}_dynamic() {`,
+    ...(minChars > 0 ? [`  (( \${#cur} >= ${minChars} )) || return 0`] : []),
+    "  local -a _matches",
+    `  _matches=("\${(f)$(${binName} __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)}")`,
+    '  (( ${#_matches[@]} == 1 )) && [[ -z "${_matches[1]}" ]] && return 0',
+    '  compadd -- "${_matches[@]}"',
+    "}",
+    `${fn}_pos() {`,
+    '  local skip="$1" vflags=" $2 " w',
+    "  local -i i",
+    "  POS=0",
+    "  for ((i = 2; i < CURRENT; i++)); do",
+    '    w="${words[i]}"',
+    '    case "$w" in',
+    '      -*) [[ "$vflags" == *" $w "* ]] && ((i++)) ;;',
+    "      *) if (( skip > 0 )); then (( skip-- )); else (( POS++ )); fi ;;",
+    "    esac",
+    "  done",
+    "}",
+    `${fn}() {`,
+    "  local cur prev noun verb w",
+    "  local -i i POS",
+    '  cur="${words[CURRENT]}"',
+    '  prev="${words[CURRENT-1]}"',
+    "  # Split an inline --flag=value word so the value routes as a flag value",
+    "  # (mirrors parse.ts). zsh keeps `--flag=value` as one word, so recover",
+    "  # $prev=flag and $cur=value before the flag-value cases below.",
+    '  if [[ "$cur" == --*=* ]]; then',
+    '    prev="${cur%%=*}"',
+    '    cur="${cur#*=}"',
+    "  fi",
+    '  noun="" verb="" POS=0',
+    "  for ((i = 2; i < CURRENT; i++)); do",
+    '    w="${words[i]}"',
+    '    case "$w" in',
+    `      ${globalValueSkips}) ((i++)) ;;`,
+    "      -*) ;;",
+    "      *)",
+    '        if [[ -z "$noun" ]]; then noun="$w"',
+    '        elif [[ -z "$verb" ]]; then verb="$w"',
+    "        fi",
+    "        ;;",
+    "    esac",
+    "  done",
+    "",
+    "  # flag values (verb-scoped, then global)",
+    ...caseBlock('"$noun/$verb/$prev"', flagValueArms(model, fn), "  "),
+    ...caseBlock('"$prev"', globalValueArms(model, fn), "  "),
+    "",
+    "  # flag names",
+    '  if [[ "$cur" == -* ]]; then',
+    ...caseBlock('"$noun/$verb"', flagNameArms(model), "    "),
+    '    if [[ -z "$noun" ]]; then',
+    `      compadd -- ${wordList(rootFlagNames(model), "zsh root flags")}`,
+    "    else",
+    `      compadd -- ${wordList(globalFlagNames(model), "zsh global flags")}`,
+    "    fi",
+    "    return 0",
+    "  fi",
+    "",
+    "  # nouns",
+    '  if [[ -z "$noun" ]]; then',
+    `    compadd -- ${wordList(nounNames(model), "zsh nouns")}`,
+    "    return 0",
+    "  fi",
+    ...verbSection,
+    "",
+    "  # positionals",
+    ...caseBlock('"$noun/$verb"', positionalArms, "  "),
+    "}",
+    `${fn} "$@"`,
+    "",
+  ];
+  return lines.join("\n");
+}