extract: join a usage line's bracket group only when it is flat

CHANGELOG.md

@@ -18,6 +18,7 @@ once it reaches a published 0.1.0 release.
 
 ### Fixed
 
+- [S-154] A nested bracket group in a usage line no longer fuses its words into one operand name, so `mandible uniq` shows `INPUT` and `OUTPUT` and `mandible env` shows `COMMAND` and `ARG` again; a flat group (`mandible mknod`'s `[MAJOR MINOR]`) still reads as one operand.
 - [S-155] A value spec written as one delimited alternation of literal values (`--compression=(xz|none|auto)`, `--crate-type <bin|lib|...>`, argparse's own `{c,java,ruby,tcl}`) now attaches as that flag's choices, instead of rendering as one opaque placeholder (`mandible grub-mkimage`, `mandible rustc`, `mandible tclobjnew-bpfcc`).
 - `xtask sweep-diff` now reports subcommand-count gains and losses per tool, separately from flags, so an invented subcommand row no longer passes as a clean sweep.
 - `xtask detector calibrate` now prints `NOT EVALUABLE` instead of `DOES NOT PASS` for a detector whose family has zero labelled members in the audit seed, so a legitimate gap in the sample is no longer reported as a failing detector.

corpus/env/9.4/expected.snap

@@ -0,0 +1,111 @@
+name: env
+description: Set each NAME to VALUE in the environment and run COMMAND.
+usage:
+- 'Usage: env [OPTION]... [-] [NAME=VALUE]... [COMMAND [ARG]...]'
+positionals:
+- name: COMMAND
+  provenance:
+    sources:
+    - help-text
+- name: ARG
+  variadic: true
+  provenance:
+    sources:
+    - help-text
+flags:
+- spellings:
+  - -i
+  - --ignore-environment
+  description: start with an empty environment
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - '-0'
+  - --null
+  description: end each output line with NUL, not newline
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -u
+  - --unset
+  value_name: NAME
+  value_kind: Required
+  description: remove variable from the environment
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -C
+  - --chdir
+  value_name: DIR
+  value_kind: Required
+  description: change working directory to DIR
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -S
+  - --split-string
+  value_name: S
+  value_kind: Required
+  description: process and split S into separate arguments; used to pass multiple arguments on shebang lines
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --block-signal
+  value_name: SIG
+  value_kind: Optional
+  description: block delivery of SIG signal(s) to COMMAND
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --default-signal
+  value_name: SIG
+  value_kind: Optional
+  description: reset handling of SIG signal(s) to the default
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --ignore-signal
+  value_name: SIG
+  value_kind: Optional
+  description: set handling of SIG signal(s) to do nothing
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --list-signal-handling
+  description: list non default signal handling to stderr
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -v
+  - --debug
+  description: print verbose information for each processing step
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --help
+  description: display this help and exit
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --version
+  description: output version information and exit
+  provenance:
+    sources:
+    - help-text
+detected_framework: GNU argp/getopt_long
+provenance:
+  sources:
+  - help-text
+  confidence: 1.0
+children_filled: true

corpus/env/9.4/help.txt

@@ -0,0 +1,34 @@
+Usage: env [OPTION]... [-] [NAME=VALUE]... [COMMAND [ARG]...]
+Set each NAME to VALUE in the environment and run COMMAND.
+
+Mandatory arguments to long options are mandatory for short options too.
+  -i, --ignore-environment  start with an empty environment
+  -0, --null           end each output line with NUL, not newline
+  -u, --unset=NAME     remove variable from the environment
+  -C, --chdir=DIR      change working directory to DIR
+  -S, --split-string=S  process and split S into separate arguments;
+                        used to pass multiple arguments on shebang lines
+      --block-signal[=SIG]    block delivery of SIG signal(s) to COMMAND
+      --default-signal[=SIG]  reset handling of SIG signal(s) to the default
+      --ignore-signal[=SIG]   set handling of SIG signal(s) to do nothing
+      --list-signal-handling  list non default signal handling to stderr
+  -v, --debug          print verbose information for each processing step
+      --help        display this help and exit
+      --version     output version information and exit
+
+A mere - implies -i.  If no COMMAND, print the resulting environment.
+
+SIG may be a signal name like 'PIPE', or a signal number like '13'.
+Without SIG, all known signals are included.  Multiple signals can be
+comma-separated.  An empty SIG argument is a no-op.
+
+Exit status:
+  125  if the env command itself fails
+  126  if COMMAND is found but cannot be invoked
+  127  if COMMAND cannot be found
+  -    the exit status of COMMAND otherwise
+
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+Report any translation bugs to <https://translationproject.org/team/>
+Full documentation <https://www.gnu.org/software/coreutils/env>
+or available locally via: info '(coreutils) env invocation'

corpus/env/9.4/meta.toml

@@ -0,0 +1,25 @@
+# docs/shapes.md S-154: `[COMMAND [ARG]...]` names two optional operands,
+# `COMMAND` and a repeatable `ARG` nested inside it. The flat multi-word
+# group rule joined them into one positional spelled `COMMAND ARG` and
+# carried the repetition marker onto that joined name, so the tree said
+# `env` takes one operand where its own synopsis names two.
+
+[bless]
+provenance = "agent"
+
+[tool]
+name = "env"
+version = "9.4"
+platform = "ubuntu-24.04"
+captured_with = "manual capture per corpus/README.md step 2 (TERM=dumb NO_COLOR=1 COLUMNS=100 LC_ALL=C.UTF-8); GNU coreutils 9.4"
+
+[[capture]]
+argv = ["env", "--help"]
+stdout = "help.txt"
+
+[contract]
+verdict_scope = ["flags", "usage"]
+expected_framework = "GNU argp/getopt_long"
+must_contain_positionals = ["COMMAND", "ARG..."]
+must_not_contain_positionals = ["COMMAND ARG"]
+must_contain_flags = ["-S", "-C", "--block-signal", "--list-signal-handling"]

corpus/uniq/9.4/expected.snap

@@ -0,0 +1,116 @@
+name: uniq
+description: Filter adjacent matching lines from INPUT (or standard input), writing to OUTPUT (or standard output).
+usage:
+- 'Usage: uniq [OPTION]... [INPUT [OUTPUT]]'
+positionals:
+- name: INPUT
+  provenance:
+    sources:
+    - help-text
+- name: OUTPUT
+  provenance:
+    sources:
+    - help-text
+flags:
+- spellings:
+  - -c
+  - --count
+  description: prefix lines by the number of occurrences
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -d
+  - --repeated
+  description: only print duplicate lines, one for each group
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -D
+  description: print all duplicate lines
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --all-repeated
+  value_name: METHOD
+  value_kind: Optional
+  description: like -D, but allow separating groups with an empty line; METHOD={none(default),prepend,separate}
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -f
+  - --skip-fields
+  value_name: N
+  value_kind: Required
+  description: avoid comparing the first N fields
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --group
+  value_name: METHOD
+  value_kind: Optional
+  description: show all items, separating groups with an empty line; METHOD={separate(default),prepend,append,both}
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -i
+  - --ignore-case
+  description: ignore differences in case when comparing
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -s
+  - --skip-chars
+  value_name: N
+  value_kind: Required
+  description: avoid comparing the first N characters
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -u
+  - --unique
+  description: only print unique lines
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -z
+  - --zero-terminated
+  description: line delimiter is NUL, not newline
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -w
+  - --check-chars
+  value_name: N
+  value_kind: Required
+  description: compare no more than N characters in lines
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --help
+  description: display this help and exit
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - --version
+  description: output version information and exit
+  provenance:
+    sources:
+    - help-text
+detected_framework: GNU argp/getopt_long
+provenance:
+  sources:
+  - help-text
+  confidence: 1.0
+children_filled: true

corpus/uniq/9.4/help.txt

@@ -0,0 +1,34 @@
+Usage: uniq [OPTION]... [INPUT [OUTPUT]]
+Filter adjacent matching lines from INPUT (or standard input),
+writing to OUTPUT (or standard output).
+
+With no options, matching lines are merged to the first occurrence.
+
+Mandatory arguments to long options are mandatory for short options too.
+  -c, --count           prefix lines by the number of occurrences
+  -d, --repeated        only print duplicate lines, one for each group
+  -D                    print all duplicate lines
+      --all-repeated[=METHOD]  like -D, but allow separating groups
+                                 with an empty line;
+                                 METHOD={none(default),prepend,separate}
+  -f, --skip-fields=N   avoid comparing the first N fields
+      --group[=METHOD]  show all items, separating groups with an empty line;
+                          METHOD={separate(default),prepend,append,both}
+  -i, --ignore-case     ignore differences in case when comparing
+  -s, --skip-chars=N    avoid comparing the first N characters
+  -u, --unique          only print unique lines
+  -z, --zero-terminated     line delimiter is NUL, not newline
+  -w, --check-chars=N   compare no more than N characters in lines
+      --help        display this help and exit
+      --version     output version information and exit
+
+A field is a run of blanks (usually spaces and/or TABs), then non-blank
+characters.  Fields are skipped before chars.
+
+Note: 'uniq' does not detect repeated lines unless they are adjacent.
+You may want to sort the input first, or use 'sort -u' without 'uniq'.
+
+GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
+Report any translation bugs to <https://translationproject.org/team/>
+Full documentation <https://www.gnu.org/software/coreutils/uniq>
+or available locally via: info '(coreutils) uniq invocation'

corpus/uniq/9.4/meta.toml

@@ -0,0 +1,26 @@
+# docs/shapes.md S-154: `[INPUT [OUTPUT]]` is a nested bracket group, so it
+# names two optional operands, `INPUT` and `OUTPUT`, the second nested
+# inside the first's own group. The rule that collapses a flat multi-word
+# group to one operand (`gdk-pixbuf-thumbnailer`'s `[INPUT FILE]`) also
+# fired here and joined the two words into one positional spelled
+# `INPUT OUTPUT`, a name the tool never documents.
+
+[bless]
+provenance = "agent"
+
+[tool]
+name = "uniq"
+version = "9.4"
+platform = "ubuntu-24.04"
+captured_with = "manual capture per corpus/README.md step 2 (TERM=dumb NO_COLOR=1 COLUMNS=100 LC_ALL=C.UTF-8); GNU coreutils 9.4"
+
+[[capture]]
+argv = ["uniq", "--help"]
+stdout = "help.txt"
+
+[contract]
+verdict_scope = ["flags", "usage"]
+expected_framework = "GNU argp/getopt_long"
+must_contain_positionals = ["INPUT", "OUTPUT"]
+must_not_contain_positionals = ["INPUT OUTPUT"]
+must_contain_flags = ["-c", "-w", "--all-repeated", "--group"]