argsbarg 3.4.2 → 3.6.0

package/justfile

@@ -1,11 +1,24 @@
 # https://github.com/casey/just — run `just` to list recipes.
 
+set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
+
 _:
     @just --list
 
-# typecheck the codebase
-check-types:
-    bun x tsc
+# check the codebase
+check: typecheck format
+
+# Update local consumer apps: npm i argsbarg@latest, build, docgen
+consumers-sync *apps:
+    #!/usr/bin/env bash
+    root="$(cd "{{justfile_directory()}}" && pwd)"
+    ss="$root/../../ss"
+    apps=(idp-trees sqsp-qa-tools sqsp-i18n-tools)
+    for app in "${apps[@]}"; do
+      dir="$(cd "$ss/$app" && pwd)"
+      echo "==> $app ($dir)"
+      (cd "$dir" && bun i argsbarg@latest && just build && just docgen && just install)
+    done
 
 # run the minimal example
 example *ARGS:
@@ -17,16 +30,20 @@ example-watch *ARGS:
 
 # format the codebase
 format:
-    bun x biome format ./src ./scripts --write
+    bun run biome check ./src ./scripts --write
 
 # lint the codebase
 lint:
-    bun x biome check ./src ./scripts
+    bun run biome check ./src ./scripts
 
 # Typecheck, lint, then run the test suite.
-test: check-types format lint
+test: check
     bun test
 
+# typecheck the codebase
+typecheck:
+    bun run tsc --noEmit
+
 # generate type declarations for the package
 typegen:
     bunx dts-bundle-generator --out-file index.d.ts src/index.ts
@@ -34,3 +51,4 @@ typegen:
 # publish to github and npm
 release bump: test typegen
     bun scripts/release.ts {{bump}}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.4.2",
+  "version": "3.6.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"
@@ -21,6 +21,8 @@
     }
   },
   "devDependencies": {
-    "@types/bun": "^1.3.12"
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "^1.3.12",
+    "typescript": "^5.9.3"
   }
 }

package/scripts/release.ts

@@ -12,7 +12,7 @@
  * repo changes (`git add -A`), not only the version and CHANGELOG edits from this script.
  */
 
-import { unlink } from "fs/promises";
+import { unlink } from "node:fs/promises";
 
 /** Returns the parent directory of an absolute file path. */
 function parentDir(absolute: string): string {
@@ -96,9 +96,13 @@ function githubRepoBaseFromOrigin(origin: string): string | null {
 function releasedSemverVersionsFromChangelog(md: string): string[] {
   const re = /^## \[(\d+\.\d+\.\d+)\] /gm;
   const out: string[] = [];
-  let m: RegExpExecArray | null;
-  while ((m = re.exec(md)) !== null) {
-    out.push(m[1]!);
+  let m = re.exec(md);
+  while (m !== null) {
+    const version = m[1];
+    if (version !== undefined) {
+      out.push(version);
+    }
+    m = re.exec(md);
   }
   return out;
 }
@@ -108,14 +112,18 @@ function releasedSemverVersionsFromChangelog(md: string): string[] {
  * (`[...]: http...`) at the end of the file.
  */
 function stripChangelogLinkDefinitions(md: string): string {
-  let s = md.replace(/\r?\n## Links\r?\n/, "\n");
+  const s = md.replace(/\r?\n## Links\r?\n/, "\n");
   const lines = s.split(/\r?\n/);
   let i = lines.length;
   while (i > 0 && lines[i - 1] === "") {
     i -= 1;
   }
   const refLine = /^\[[^\]]+\]: .+$/;
-  while (i > 0 && refLine.test(lines[i - 1]!)) {
+  while (i > 0) {
+    const line = lines[i - 1];
+    if (line === undefined || !refLine.test(line)) {
+      break;
+    }
     i -= 1;
   }
   while (i > 0 && lines[i - 1] === "") {
@@ -143,7 +151,10 @@ function appendChangelogLinkDefinitions(md: string, repoBase: string): string {
   if (versions.length === 0) {
     return `${body}\n`;
   }
-  const newest = versions[0]!;
+  const newest = versions[0];
+  if (newest === undefined) {
+    return `${body}\n`;
+  }
   const lines = [
     "",
     "",
@@ -178,7 +189,9 @@ function promoteChangelog(content: string, version: string, date: string): strin
   const bodyStart = lineEnd + 1;
   const nextIdx = content.indexOf("\n## [", bodyStart);
   const body =
-    nextIdx === -1 ? content.slice(bodyStart).trimEnd() : content.slice(bodyStart, nextIdx).trimEnd();
+    nextIdx === -1
+      ? content.slice(bodyStart).trimEnd()
+      : content.slice(bodyStart, nextIdx).trimEnd();
   const tail = nextIdx === -1 ? "" : content.slice(nextIdx + 1);
   const before = content.slice(0, idx);
   const newBlock = `${header}\n\n## [${version}] - ${date}\n${body}\n\n`;
@@ -240,7 +253,11 @@ try {
   run("git tag", ["git", "tag", "-a", tag, "-m", msg], repoRoot);
   run("git push", ["git", "push"], repoRoot);
   run("git push tags", ["git", "push", "--tags"], repoRoot);
-  run("gh release", ["gh", "release", "create", tag, "--title", tag, "--notes-file", notesPath], repoRoot);
+  run(
+    "gh release",
+    ["gh", "release", "create", tag, "--title", tag, "--notes-file", notesPath],
+    repoRoot,
+  );
   run("npm publish", ["npm", "publish"], repoRoot);
 } finally {
   await unlink(notesPath).catch(() => {});

package/src/builtins/builtins.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, test } from "bun:test";
+import type { CliProgram } from "../types.ts";
+import { exportPresentationBuiltins } from "./export.ts";
+import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
 import { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliPresentationRoot } from "./presentation.ts";
-import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
-import { exportPresentationBuiltins } from "./export.ts";
-import { CliProgram } from "../types.ts";
 
 const fixture: CliProgram = {
   key: "myapp",
@@ -114,7 +114,12 @@ describe("completion emitters", () => {
   });
 
   test("zsh script registers compdef", () => {
-    const schema = cliPresentationRoot({ key: "zapp", version: "0.0.0", description: "z", handler: () => {} });
+    const schema = cliPresentationRoot({
+      key: "zapp",
+      version: "0.0.0",
+      description: "z",
+      handler: () => {},
+    });
     const zsh = completionZshScript(schema);
     expect(zsh).toContain("#compdef zapp");
     expect(zsh).toContain("compdef _zapp zapp");

package/src/builtins/completion-bash.ts

@@ -1,4 +1,4 @@
-import { CliNode, CliRouter, CliOptionKind } from "../types.ts";
+import { CliOptionKind, type CliRouter } from "../types.ts";
 import { collectScopes, type ScopeRec } from "./scopes.ts";
 import {
   escShellSingleQuoted,
@@ -10,19 +10,24 @@ import {
 
 function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
   let o = "_${ident}_nac_consume_long() {\n".replace("${ident}", ident);
-  o += "  local sid=\"$1\" w=\"$2\" nw=\"$3\"\n";
+  o += '  local sid="$1" w="$2" nw="$3"\n';
   o += "  case $sid in\n";
   for (const [i, sc] of scopes.entries()) {
-    o += "    " + i + ")\n";
+    o += `    ${i})\n`;
     o += "      case $w in\n";
-    o += "        " + kHelpLong + "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n".replace(/\$\{kHelpLong\}/g, kHelpLong).replace(/\$\{kHelpShort\}/g, kHelpShort);
+    o +=
+      "        " +
+      kHelpLong +
+      "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n"
+        .replace(/\$\{kHelpLong\}/g, kHelpLong)
+        .replace(/\$\{kHelpShort\}/g, kHelpShort);
     for (const op of sc.opts) {
-      const base = "--" + op.name;
+      const base = `--${op.name}`;
       if (op.kind === "presence") {
-        o += "        " + base + "|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base);
+        o += `        ${base}${"|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base)}`;
       } else {
-        o += "        " + base + "=*) echo 1 ;;\n";
-        o += "        " + base + ") echo 2 ;;\n";
+        o += `        ${base}=*) echo 1 ;;\n`;
+        o += `        ${base}) echo 2 ;;\n`;
       }
     }
     o += "        *) echo 0 ;;\n";
@@ -37,10 +42,10 @@ function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
 
 function emitConsumeShort(ident: string, scopes: ScopeRec[]): string {
   let o = "_${ident}_nac_consume_short() {\n".replace("${ident}", ident);
-  o += "  local sid=\"$1\" w=\"$2\"\n";
+  o += '  local sid="$1" w="$2"\n';
   o += "  case $sid in\n";
   for (const [i, sc] of scopes.entries()) {
-    o += "    " + i + ")\n";
+    o += `    ${i})\n`;
     o += "      local rest=${w#-}\n";
     o += "      local ch\n";
     o += "      local saw=0\n";
@@ -52,16 +57,16 @@ function emitConsumeShort(ident: string, scopes: ScopeRec[]): string {
     for (const op of sc.opts) {
       if (!op.shortName) continue;
       if (op.kind === "presence") {
-        boolChars += op.shortName + "|";
+        boolChars += `${op.shortName}|`;
       } else {
-        o += "          " + op.shortName + ")\n";
+        o += `          ${op.shortName})\n`;
         o += "            if [[ $saw -ne 0 || -n $rest ]]; then echo 0; return; fi\n";
         o += "            echo 2; return ;;\n";
       }
     }
     if (boolChars.length > 0) {
       boolChars = boolChars.slice(0, -1);
-      o += "          " + boolChars + ") ;;\n";
+      o += `          ${boolChars}) ;;\n`;
     }
     o += "          *) echo 0; return ;;\n";
     o += "        esac\n";
@@ -76,18 +81,22 @@ function emitConsumeShort(ident: string, scopes: ScopeRec[]): string {
   return o;
 }
 
-function emitMatchChild(ident: string, scopes: ScopeRec[], pathIndex: Record<string, number>): string {
+function emitMatchChild(
+  ident: string,
+  scopes: ScopeRec[],
+  pathIndex: Record<string, number>,
+): string {
   let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
-  o += "  local sid=\"$1\" w=\"$2\"\n";
+  o += '  local sid="$1" w="$2"\n';
   o += "  case $sid in\n";
   for (const [sid, sc] of scopes.entries()) {
     if (sc.kids.length === 0) continue;
-    o += "    " + sid + ")\n";
+    o += `    ${sid})\n`;
     o += "      case $w in\n";
     for (const ch of sc.kids) {
-      const childPath = sc.path === "" ? ch.key : sc.path + "/" + ch.key;
+      const childPath = sc.path === "" ? ch.key : `${sc.path}/${ch.key}`;
       const cid = pathIndex[childPath] ?? 0;
-      o += "        " + ch.key + ") echo " + cid + "; return 0 ;;\n";
+      o += `        ${ch.key}) echo ${cid}; return 0 ;;\n`;
     }
     o += "      esac\n";
     o += "      ;;\n";
@@ -102,12 +111,15 @@ function emitSimulate(ident: string): string {
   let o = "_${ident}_nac_simulate() {\n".replace("${ident}", ident);
   o += "  local i=1 sid=0 w steps next\n";
   o += "  while (( i < COMP_CWORD )); do\n";
-  o += "    w=\"${COMP_WORDS[i]}\"\n";
-  o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " ]]; then\n";
+  o += '    w="${COMP_WORDS[i]}"\n';
+  o += `    if [[ $w == ${kHelpShort} || $w == ${kHelpLong} ]]; then\n`;
   o += "      ((i++)); continue\n";
   o += "    fi\n";
   o += "    if [[ $w == --* ]]; then\n";
-  o += "      steps=$(_${ident}_nac_consume_long \"$sid\" \"$w\" \"${COMP_WORDS[i+1]}\")\n".replace("${ident}", ident);
+  o += '      steps=$(_${ident}_nac_consume_long "$sid" "$w" "${COMP_WORDS[i+1]}")\n'.replace(
+    "${ident}",
+    ident,
+  );
   o += "      case $steps in\n";
   o += "        0) break ;;\n";
   o += "        1) ((i++)) ;;\n";
@@ -117,7 +129,7 @@ function emitSimulate(ident: string): string {
   o += "      continue\n";
   o += "    fi\n";
   o += "    if [[ $w == -* ]]; then\n";
-  o += "      steps=$(_${ident}_nac_consume_short \"$sid\" \"$w\")\n".replace("${ident}", ident);
+  o += '      steps=$(_${ident}_nac_consume_short "$sid" "$w")\n'.replace("${ident}", ident);
   o += "      case $steps in\n";
   o += "        0) break ;;\n";
   o += "        1) ((i++)) ;;\n";
@@ -126,7 +138,7 @@ function emitSimulate(ident: string): string {
   o += "      esac\n";
   o += "      continue\n";
   o += "    fi\n";
-  o += "    next=$(_${ident}_nac_match_child \"$sid\" \"$w\") || break\n".replace("${ident}", ident);
+  o += '    next=$(_${ident}_nac_match_child "$sid" "$w") || break\n'.replace("${ident}", ident);
   o += "    sid=$next\n";
   o += "    ((i++))\n";
   o += "  done\n";
@@ -137,16 +149,23 @@ function emitSimulate(ident: string): string {
 
 function emitEnumReplyBash(ident: string, scopes: ScopeRec[]): string {
   let o = "_${ident}_nac_enum_reply() {\n".replace("${ident}", ident);
-  o += "  local sid=\"$1\" prev=\"$2\" cur=\"$3\"\n";
+  o += '  local sid="$1" prev="$2" cur="$3"\n';
   o += "  case $sid in\n";
   for (const [i, sc] of scopes.entries()) {
-    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
+    const enumOpts = sc.opts.filter(
+      (op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0,
+    );
     if (enumOpts.length === 0) continue;
-    o += "    " + i + ")\n";
+    o += `    ${i})\n`;
     o += "      case $prev in\n";
     for (const op of enumOpts) {
       const words = (op.choices ?? []).map((c) => escShellSingleQuoted(c)).join(" ");
-      o += "        --" + op.name + ") COMPREPLY=( $(compgen -W '" + words + "' -- \"$cur\") ); return 0 ;;\n";
+      o +=
+        "        --" +
+        op.name +
+        ") COMPREPLY=( $(compgen -W '" +
+        words +
+        '\' -- "$cur") ); return 0 ;;\n';
     }
     o += "      esac\n";
     o += "      ;;\n";
@@ -160,34 +179,39 @@ function emitEnumReplyBash(ident: string, scopes: ScopeRec[]): string {
 function emitMainBodyBash(schema: CliRouter, ident: string): string {
   const main = mainName(schema.key);
   let o = "_${main}() {\n".replace("${main}", main);
-  o += "  local cur=\"${COMP_WORDS[COMP_CWORD]}\"\n";
-  o += "  local prev=\"${COMP_WORDS[COMP_CWORD-1]:-}\"\n";
+  o += '  local cur="${COMP_WORDS[COMP_CWORD]}"\n';
+  o += '  local prev="${COMP_WORDS[COMP_CWORD-1]:-}"\n';
   o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
   o += "  local sid=$REPLY_SID\n";
-  o += "  if _${ident}_nac_enum_reply \"$sid\" \"$prev\" \"$cur\"; then return; fi\n".replace("${ident}", ident);
+  o += '  if _${ident}_nac_enum_reply "$sid" "$prev" "$cur"; then return; fi\n'.replace(
+    "${ident}",
+    ident,
+  );
   o += "  if [[ $cur == -* ]]; then\n";
-  o += "    local oname=\"A_${ident}_${sid}_opts\"\n".replace("${ident}", ident);
+  o += '    local oname="A_${ident}_${sid}_opts"\n'.replace("${ident}", ident);
   o += "    local -a optsarr\n";
-  o += "    local -n optsref=\"$oname\"\n";
-  o += "    COMPREPLY=( $(compgen -W \"${optsref[*]}\" -- \"$cur\") )\n";
+  o += '    local -n optsref="$oname"\n';
+  o += '    COMPREPLY=( $(compgen -W "${optsref[*]}" -- "$cur") )\n';
   o += "  else\n";
-  o += "    local lname=\"A_${ident}_${sid}_leaf\"\n".replace("${ident}", ident);
-  o += "    local -n leafref=\"$lname\"\n";
+  o += '    local lname="A_${ident}_${sid}_leaf"\n'.replace("${ident}", ident);
+  o += '    local -n leafref="$lname"\n';
   o += "    if [[ $leafref -eq 0 ]]; then\n";
-  o += "      local cname=\"A_${ident}_${sid}_cmds\"\n".replace("${ident}", ident);
+  o += '      local cname="A_${ident}_${sid}_cmds"\n'.replace("${ident}", ident);
   o += "      local -a cmdsarr\n";
-  o += "      local -n cmdsref=\"$cname\"\n";
-  o += "      COMPREPLY=( $(compgen -W \"${cmdsref[*]}\" -- \"$cur\") )\n";
+  o += '      local -n cmdsref="$cname"\n';
+  o += '      COMPREPLY=( $(compgen -W "${cmdsref[*]}" -- "$cur") )\n';
   o += "    else\n";
-  o += "      local pname=\"A_${ident}_${sid}_pos\"\n".replace("${ident}", ident);
-  o += "      local -n posref=\"$pname\"\n";
+  o += '      local pname="A_${ident}_${sid}_pos"\n'.replace("${ident}", ident);
+  o += '      local -n posref="$pname"\n';
   o += "      if [[ $posref -eq 1 ]]; then\n";
   o += "        compopt -o filenames\n";
   o += "      fi\n";
   o += "    fi\n";
   o += "  fi\n";
   o += "}\n\n";
-  o += "complete -F _${main} ${schema.key}\n".replace("${main}", main).replace("${schema.key}", schema.key);
+  o += "complete -F _${main} ${schema.key}\n"
+    .replace("${main}", main)
+    .replace("${schema.key}", schema.key);
   return o;
 }
 
@@ -200,23 +224,23 @@ export function completionBashScript(schema: CliRouter): string {
     pathIndex[s.path] = i;
   }
 
-  let out = "# Generated bash completion for " + schema.key + ".\n\n";
+  let out = `# Generated bash completion for ${schema.key}.\n\n`;
 
   for (const [i, sc] of scopes.entries()) {
-    out += "A_" + ident + "_" + i + "_opts=()\n";
-    out += "A_" + ident + "_" + i + "_opts+=('" + kHelpLong + "' '" + kHelpShort + "')\n";
+    out += `A_${ident}_${i}_opts=()\n`;
+    out += `A_${ident}_${i}_opts+=('${kHelpLong}' '${kHelpShort}')\n`;
     for (const o of sc.opts) {
-      out += "A_" + ident + "_" + i + "_opts+=('--" + o.name + "')\n";
+      out += `A_${ident}_${i}_opts+=('--${o.name}')\n`;
       if (o.shortName) {
-        out += "A_" + ident + "_" + i + "_opts+=('-" + o.shortName + "')\n";
+        out += `A_${ident}_${i}_opts+=('-${o.shortName}')\n`;
       }
     }
-    out += "A_" + ident + "_" + i + "_leaf=" + (sc.kids.length === 0 ? "1" : "0") + "\n";
-    out += "A_" + ident + "_" + i + "_pos=" + (sc.wantsFiles ? "1" : "0") + "\n";
+    out += `A_${ident}_${i}_leaf=${sc.kids.length === 0 ? "1" : "0"}\n`;
+    out += `A_${ident}_${i}_pos=${sc.wantsFiles ? "1" : "0"}\n`;
     if (sc.kids.length > 0) {
-      out += "A_" + ident + "_" + i + "_cmds=(";
+      out += `A_${ident}_${i}_cmds=(`;
       for (const ch of sc.kids) {
-        out += " '" + ch.key + "'";
+        out += ` '${ch.key}'`;
       }
       out += ")\n";
     }

package/src/builtins/completion-fish.ts

@@ -1,11 +1,6 @@
-import { CliNode, CliRouter, CliOptionKind } from "../types.ts";
+import { CliOptionKind, type CliRouter } from "../types.ts";
 import { collectScopes } from "./scopes.ts";
-import {
-  escFishSingleQuoted,
-  identToken,
-  kHelpLong,
-  kHelpShort,
-} from "./shell-helpers.ts";
+import { escFishSingleQuoted, identToken } from "./shell-helpers.ts";
 
 function scopeCondition(ident: string, scopeIndex: number, path: string): string {
   const fn = `__${ident}_scope_${scopeIndex}`;
@@ -30,7 +25,7 @@ export function completionFishScript(schema: CliRouter): string {
   const app = schema.key;
   const scopes = collectScopes(schema);
 
-  let out = "# Fish completion for " + app + "\n\n";
+  let out = `# Fish completion for ${app}\n\n`;
 
   for (const [i, sc] of scopes.entries()) {
     out += scopeCondition(ident, i, sc.path);

package/src/builtins/completion-group.ts

@@ -1,5 +1,5 @@
 import { resolveCapabilities } from "../capabilities.ts";
-import { type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
+import type { CliProgram, CliRouter } from "../types.ts";
 
 /**
  * Builds the static `completion` / `bash` / `zsh` / `fish` command subtree (merged into the program root at runtime).