Fix mis-modelled multi-arg options: text, data and file utility specs by warp-agent-staging[bot] · Pull Request #343 · warpdotdev/command-signatures

warp-agent-staging · 2026-08-23T21:42:48Z

What

Follow-up to #341 (ln -s/-F/-f/-i), covering the text, data and file utilities:
jq, rg, rsync, pandoc, sqlite3, unzip, vim, date, dog.

An option that declares two or more args hits a completer bug where the last
declared argument is resolved no matter which value you are typing, so a
mis-modelled option actively breaks completion rather than just describing the
tool wrongly. This PR corrects the spec data for the options in that group that
were modelling one value (or a value set, or the command's own operands) as
several arguments.

Every option below was checked against the tool's own ground truth before it was
touched. Where the tool is installed here it was run; otherwise the official
documentation is named. Nothing was changed on the basis of how the argument
names in our spec read.

Changed

`rsync --info` / `--debug` — a value set enumerated as args

Both declared fifteen arguments (BACKUP, COPY, DEL, FLIST, …). Both
take a single comma-separated FLAGS token.

Evidence (rsync 3.2.7, rsync --help):

--info=FLAGS             fine-grained informational verbosity
--debug=FLAGS            fine-grained debug verbosity

rsync --info=help prefaces its list with "Use OPT or OPT1 for level 1 output,
OPT2 for level 2, etc.; OPT0 silences." Confirmed empirically — a second token
is consumed as a source path, not as a flag:

$ rsync -a --info=NAME,STATS2,FLIST0 rsrc/ rdst/     # ok
$ rsync -a --info=NAME STATS rsrc/ rdst2/
rsync: [sender] link_stat "/tmp/STATS" failed: No such file or directory (2)

Now one FLAGS argument carrying the flag names as suggestions. Two corrections
came with it, both from the tool:

--debug was carrying a verbatim copy of the --info flag list. Replaced
with the real one from rsync --debug=help (ACL, BACKUP, BIND, CHDIR,
CONNECT, CMD, DEL, DELTASUM, DUP, EXIT, FILTER, FLIST, FUZZY,
GENR, HASH, HLINK, ICONV, IO, NSTR, OWN, PROTO, RECV, SEND,
TIME, plus ALL/NONE/HELP), and its ALL/NONE descriptions now say
"--debug options" rather than "--info options".
--info gained NONREG, which is in rsync --info=help and was missing.

Suggestion descriptions are --info=help / --debug=help text verbatim.

`rg --dfa-size-limit` / `--max-filesize` / `--regex-size-limit` — one value modelled as two

Each declared [NUM, suffix]. The suffix is part of one token.

Evidence (ripgrep 14.1.0, rg --help):

--max-filesize=NUM+SUFFIX?
    Ignore files larger than NUM in size. …
    The input format accepts suffixes of K, M or G … If no suffix is
    provided the input is treated as bytes.
    Examples: --max-filesize 50K or --max-filesize 80M.

--dfa-size-limit=NUM+SUFFIX? and --regex-size-limit=NUM+SUFFIX? carry the
same wording. Confirmed empirically:

$ rg --max-filesize 50K hello rgtest/     # matches
$ rg --max-filesize 50 K hello rgtest/
rg: hello: No such file or directory (os error 2)   # "K" became the pattern

Collapsed to a single NUM+SUFFIX argument, with the format documented in the
argument description.

`pandoc -M/--metadata` and `-V/--variable` — one value modelled as two

Each declared [key, value]. Both take a single colon-joined token.

Evidence (pandoc 3.1.3, pandoc --help):

-M KEY[:VALUE]        --metadata=KEY[:VALUE]
-V KEY[:VALUE]        --variable=KEY[:VALUE]

Confirmed empirically:

$ pandoc -M title:MyTitle -s -t html p.md    →  <title>MyTitle</title>
$ pandoc -M title MyTitle -s -t html p.md
pandoc: MyTitle: withBinaryFile: does not exist   # second token read as an input file

Collapsed to a single KEY[:VALUE] argument.

`vim -V` — one value modelled as two (fused token)

Declared [N, fname]. Real syntax attaches both parts to the flag itself, so
there is no separate value token at all.

Evidence (Vim 9.1, vim --help):

-V[N][fname]		Be verbose [level N] [log messages to fname]

Confirmed empirically — fused writes the log, separated does not:

$ vim -V9/tmp/vlog1.txt -es -c 'qa!' </dev/null   →  /tmp/vlog1.txt written
$ vim -V 9 /tmp/vlog2.txt -es -c 'qa!' </dev/null →  no log; "9" and the path opened as files

Collapsed to one optional [N][fname] argument, consistent with how this spec
already models -p[N], -o[N] and -O[N].

`date -f` — operands written into the option

Declared [input_fmt, new_date]. -f consumes only input_fmt; new_date is
date's own operand, already modelled by the spec's top-level
new_time OR output_fmt argument. This is exactly the ln -s shape.

This spec models BSD/macOS date (-j, -R, -v, -t), which is not the
date installed here, so ground truth is the official FreeBSD date(1) man
page (FreeBSD 14.0-RELEASE):

SYNOPSIS
     date [-jnRu] … -f input_fmt new_date [+output_fmt]

     -f input_fmt
	     Use input_fmt as the format string to parse the new_date provided
	     rather than using the default [[[[[cc]yy]mm]dd]HH]MM[.SS] format.

new_date removed from the option.

`dog --color` (ten copies) — operands written into the option

Declared [arguments, WHEN], where arguments is a verbatim copy of dog's own
top-level positional — same name and same description ("Human-readable host
names, nameservers, types, or classes"). The ten occurrences are ten independent
copies in dog.json (root plus nine subcommand paths: A, MX, CNAME, TXT,
NS, SOA, TTL, ANY +noall +answer, and the +nocomments … path), not one
shared definition; all ten are fixed identically.

The dog binary shipped for Linux (v0.1.0) will not run here (it links
libssl.so.1.1), so ground truth is the man page shipped in the same release
archive:

--color, --colour=WHEN
When to colourise the output.
This can be `always', `automatic', or `never'.

Corroborated by dog's own shipped fish completion, which offers exactly
always / automatic / never for the flag.

arguments removed; the remaining WHEN argument now carries those three
values as suggestions, matching how ls --color is already modelled in this
repo.

`unzip -0` — deleted; the option does not exist

Declared [gbk, file], where file is unzip's own operand (unzip [-opts] file[.zip] [list]) and gbk is a charset value rather than an argument name.
But the flag itself is not real: Info-ZIP UnZip 6.00 has no -0 at all.

$ unzip -0 t.zip
… usage message …            # exit 10
$ unzip -h
  -O CHARSET  specify a character encoding for DOS, Windows and OS/2 archives

The entry is almost certainly a digit-zero/letter-O mix-up for -O CHARSET. An
earlier revision of this PR fixed only the arity and kept the entry, which was
the wrong call: a well-formed CHARSET argument on a flag that does not exist
invites more trust than the broken version did. The entry is now removed.

Removing it deliberately does not settle what the correct spelling is. -O and
-I come from the Debian charset patch and are absent from stock Info-ZIP on
macOS, so adding -O is a platform decision outside this audit's class of
error — and deleting the digit-zero entry does not require answering it. See
"Flagged" below.

Verified correct, left alone

jq --arg, --argjson, --slurpfile, --rawfile — genuinely two-valued.
jq 1.7 jq --help:

--arg name value      set $name to the string value;
--argjson name value  set $name to the JSON value;
--slurpfile name file set $name to an array of JSON values read
                      from the file;
--rawfile name file   set $name to string contents of file;

sqlite3 -lookaside, -pagecache — genuinely two-valued. SQLite 3.45.1
sqlite3 -help:

-lookaside SIZE N    use N entries of SZ bytes for lookaside memory
-pagecache SIZE N    use N slots of SZ bytes each for page cache memory

Flagged, not changed

unzip has no charset option after this PR. The deleted -0 entry was the
spec's only attempt at one. Adding the real -O CHARSET (and its sibling
-I CHARSET) is the open follow-up, and it needs a platform decision first:
both come from the Debian charset patch and are absent from stock Info-ZIP on
macOS, so a spec that offers them unconditionally would suggest flags that do
not exist for macOS users.
rsync --info/--debug carry "requiresSeparator": true, which is a Fig
field name; this repo's CommandOption type reads requiresEquals, so the
field is silently ignored on deserialize. Pre-existing, unrelated to arity,
left as-is.

Unresolved

None. Every option in the assigned group was settled against the tool's own help
output, its shipped man page, or the official man page named above.

Testing

cargo test -p warp-command-signatures — 176 passed, 0 failed.
npm run format:check — all matched files use Prettier code style.

cla-bot · 2026-08-23T21:42:51Z

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: wilson.
This is most likely caused by a git client misconfiguration; please make sure to:

check if your git client is configured with an email to sign commits git config --list | grep email
If not, set it up using git config --global user.email email@example.com
Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

warp-agent-staging · 2026-08-23T21:43:24Z

This PR was generated with Warp.

Comment @warp-factory on this PR to send it follow-up work.

cla-bot · 2026-08-23T21:57:03Z

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: wilson.
This is most likely caused by a git client misconfiguration; please make sure to:

check if your git client is configured with an email to sign commits git config --list | grep email
If not, set it up using git config --global user.email email@example.com
Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

warp-agent-staging

Per Andy's request, here is per-hunk reasoning inline: why each change is right and the evidence that settles it. This annotates my own work, so it is a comment review rather than a verdict.

Two things I verified and deliberately left alone can't take an inline comment, because their files aren't in this diff:

jq --arg, --argjson, --slurpfile, --rawfile (command-signatures/json/jq.json) — genuinely two-valued, so untouched. jq 1.7 --help: --arg name value, --argjson name value, --slurpfile name file, --rawfile name file.
sqlite3 -lookaside, -pagecache (command-signatures/json/sqlite3.json) — likewise. SQLite 3.45.1 sqlite3 -help: -lookaside SIZE N use N entries of SZ bytes for lookaside memory and -pagecache SIZE N use N slots of SZ bytes each for page cache memory.

dog --color is ten copies of a single mistake, so the reasoning is written once on the first copy and the other nine point at it rather than repeating it.

Responding as wilson: Open session · View in factory

warp-agent-staging · 2026-08-23T22:27:57Z

-                }
-            ]
+            "args": {
+                "name": "FLAGS",


rsync's own help spells this --info=FLAGS — one value, not fifteen. rsync --info=help prefaces its list with "Use OPT or OPT1 for level 1 output, OPT2 for level 2, etc.; OPT0 silences", so the names are items inside one comma-separated token such as NAME2,STATS3,FLIST0; they were never separate argv words. Confirmed by running it — rsync -a --info=NAME STATS rsrc/ rdst2/ fails with link_stat "/tmp/STATS" failed, because rsync reads STATS as a source path.

NONREG is new here: --info=help lists it and the spec didn't have it.

warp-agent-staging · 2026-08-23T22:27:57Z

-                }
-            ]
+            "args": {
+                "name": "FLAGS",


Same FLAGS shape as --info, but there is a second defect here that the diff cannot show: the fifteen removed args were a verbatim copy of the --info list, down to the ALL/NONE descriptions reading "--info options". Not one of --debug's own flags was present, so the old entry offered the wrong vocabulary entirely.

The suggestions now come from rsync --debug=help: 24 real flags (ACL, BIND, CHDIR, DELTASUM, DUP, GENR, HASH, HLINK, ICONV, NSTR, PROTO, RECV, SEND …) plus ALL/NONE/HELP, with that command's descriptions verbatim.

warp-agent-staging · 2026-08-23T22:27:57Z

-                }
-            ]
+            "args": {
+                "name": "NUM+SUFFIX",


rg --help spells this --dfa-size-limit=NUM+SUFFIX? — the suffix belongs to the same token, so NUM and suffix were never two values. The help block continues: "The input format accepts suffixes of K, M or G … If no suffix is provided the input is treated as bytes", which is what the new description records.

warp-agent-staging · 2026-08-23T22:27:57Z

-                }
-            ]
+            "args": {
+                "name": "NUM+SUFFIX",


--max-filesize=NUM+SUFFIX?, and its help block ends "Examples: --max-filesize 50K or --max-filesize 80M" — one token each. This is the flag I used to prove the shape for all three: rg --max-filesize 50 K hello rgtest/ exits 2 with rg: hello: No such file or directory, because ripgrep took K as the pattern and hello as a path.

warp-agent-staging · 2026-08-23T22:27:57Z

-                }
-            ]
+            "args": {
+                "name": "NUM+SUFFIX",


--regex-size-limit=NUM+SUFFIX? in rg --help, the same single-token format as the two size limits above and collapsed for the same reason. The K/M/G wording is kept in the description so the format is discoverable from the completion menu itself.

warp-agent-staging · 2026-08-23T22:27:58Z

-                        }
-                    ]
+                    "args": {
+                        "name": "WHEN",


dog NS --color: copy of the same mistake, same fix — reasoning on the root --color hunk earlier in this review.

warp-agent-staging · 2026-08-23T22:27:58Z

-                        }
-                    ]
+                    "args": {
+                        "name": "WHEN",


dog SOA --color: copy of the same mistake, same fix — reasoning on the root --color hunk earlier in this review.

warp-agent-staging · 2026-08-23T22:27:58Z

-                        }
-                    ]
+                    "args": {
+                        "name": "WHEN",


dog TTL --color: copy of the same mistake, same fix — reasoning on the root --color hunk earlier in this review.

warp-agent-staging · 2026-08-23T22:27:58Z

-                        }
-                    ]
+                    "args": {
+                        "name": "WHEN",


dog ANY +noall +answer --color: copy of the same mistake, same fix — reasoning on the root --color hunk earlier in this review.

warp-agent-staging · 2026-08-23T22:27:58Z

-                        }
-                    ]
+                    "args": {
+                        "name": "WHEN",


dog +nocomments … --color: copy of the same mistake, same fix — reasoning on the root --color hunk earlier in this review.

warp-for-oss · 2026-08-23T22:31:54Z

@acarl005

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

acarl005 · 2026-08-23T22:32:14Z

@cla-bot check

cla-bot · 2026-08-23T22:32:17Z

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: wilson.
This is most likely caused by a git client misconfiguration; please make sure to:

check if your git client is configured with an email to sign commits git config --list | grep email
If not, set it up using git config --global user.email email@example.com
Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

cla-bot · 2026-08-23T22:32:18Z

The cla-bot has been summoned, and re-checked this pull request!

warp-for-oss

Overview

This PR updates static command-signature JSON specs to collapse mis-modeled multi-argument options into the single tokens those CLIs actually accept, replace copied positional operands with scoped option arguments or suggestions, and remove an invalid unzip -0 entry.

Concerns

None. I found no correctness, security, comment-quality, test-quality, or spec-alignment issues in the annotated diff. No approved or repository spec context was provided for additional implementation comparison.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

acarl005 · 2026-08-24T02:12:15Z

@cla-bot check

cla-bot · 2026-08-24T02:12:17Z

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: wilson.
This is most likely caused by a git client misconfiguration; please make sure to:

check if your git client is configured with an email to sign commits git config --list | grep email
If not, set it up using git config --global user.email email@example.com
Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

cla-bot · 2026-08-24T02:12:19Z

The cla-bot has been summoned, and re-checked this pull request!

Follow-up to #341. Options that declare two or more args hit a completer bug where the last declared argument is resolved regardless of which value is being typed, so these were breaking completion, not just describing the tools wrongly. - rsync --info/--debug: fifteen args -> one comma-separated FLAGS argument with the flag names as suggestions. --debug was carrying a copy of the --info flag list; replaced with the real one from rsync --debug=help. --info gained the missing NONREG. - rg --dfa-size-limit/--max-filesize/--regex-size-limit: [NUM, suffix] -> one NUM+SUFFIX token. - pandoc -M/--metadata and -V/--variable: [key, value] -> one KEY[:VALUE] token. - vim -V: [N, fname] -> one optional [N][fname] token fused to the flag. - date -f: dropped new_date, which is date's own operand. - dog --color (ten copies): dropped dog's own positional; WHEN now carries always/automatic/never as suggestions. - unzip -0: dropped unzip's own file operand; one CHARSET argument. jq --arg/--argjson/--slurpfile/--rawfile and sqlite3 -lookaside/-pagecache were verified as genuinely two-valued and left unchanged.

Info-ZIP UnZip 6.00 has no -0: "unzip -0 t.zip" exits 10 and prints usage, and "unzip -h" documents -O CHARSET with no -0 anywhere. The previous commit fixed only the entry's arity and kept it, which made an invalid spelling more prominent - a well-formed CHARSET argument on a flag that does not exist invites more trust than the broken version did. Removing the entry does not settle what the correct spelling is. -O and -I come from the Debian charset patch and are absent from stock Info-ZIP on macOS, so adding -O is a platform decision outside this audit's class of error, and deleting the digit-zero entry does not require answering it.

warp-agent-staging Bot added the factory:wilson label Aug 23, 2026

warp-agent-staging Bot commented Aug 23, 2026

View reviewed changes

acarl005 marked this pull request as ready for review August 23, 2026 22:31

warp-for-oss Bot reviewed Aug 23, 2026

View reviewed changes

acarl005 approved these changes Aug 24, 2026

View reviewed changes

acarl005 self-assigned this Aug 24, 2026

warp-agent-staging Bot added 2 commits August 24, 2026 02:15

warp-agent-staging Bot force-pushed the factory/spec-audit-text-data-file-utils branch from 4ddfde7 to c6505a5 Compare August 24, 2026 02:15

cla-bot Bot added the cla-signed label Aug 24, 2026

acarl005 merged commit 010dcd2 into main Aug 24, 2026
8 checks passed

acarl005 deleted the factory/spec-audit-text-data-file-utils branch August 24, 2026 02:37

Uh oh!

Conversation

warp-agent-staging Bot commented Aug 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Changed

rsync --info / --debug — a value set enumerated as args

rg --dfa-size-limit / --max-filesize / --regex-size-limit — one value modelled as two

pandoc -M/--metadata and -V/--variable — one value modelled as two

vim -V — one value modelled as two (fused token)

date -f — operands written into the option

dog --color (ten copies) — operands written into the option

unzip -0 — deleted; the option does not exist

Verified correct, left alone

Flagged, not changed

Unresolved

Testing

Uh oh!

cla-bot Bot commented Aug 23, 2026

Uh oh!

warp-agent-staging Bot commented Aug 23, 2026

Uh oh!

cla-bot Bot commented Aug 23, 2026

Uh oh!

warp-agent-staging Bot left a comment

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-agent-staging Bot Aug 23, 2026

Choose a reason for hiding this comment

Uh oh!

warp-for-oss Bot commented Aug 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

acarl005 commented Aug 23, 2026

Uh oh!

cla-bot Bot commented Aug 23, 2026

Uh oh!

cla-bot Bot commented Aug 23, 2026

Uh oh!

warp-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

acarl005 commented Aug 24, 2026

Uh oh!

cla-bot Bot commented Aug 24, 2026

Uh oh!

cla-bot Bot commented Aug 24, 2026

Uh oh!

Uh oh!

Reviewers

warp-agent-staging Bot commented Aug 23, 2026 •

edited

Loading

`rsync --info` / `--debug` — a value set enumerated as args

`rg --dfa-size-limit` / `--max-filesize` / `--regex-size-limit` — one value modelled as two

`pandoc -M/--metadata` and `-V/--variable` — one value modelled as two

`vim -V` — one value modelled as two (fused token)

`date -f` — operands written into the option

`dog --color` (ten copies) — operands written into the option

`unzip -0` — deleted; the option does not exist

warp-for-oss Bot commented Aug 23, 2026 •

edited

Loading