Parser follow-ups from the multi-spelling / choices / argfile rounds

[sadigaxund]

One tracking issue for the measured-but-unshipped leftovers of #95–#101. Each item has a repro and a reason it did not ship; none is a regression.

1. Alias-run fold needs a real discriminator

Adjacent single-spelling rows with identical description, value and at most one long-like name still fabricate merges: as -w/-X (both "Ignored."), lto-dump -C/-CC (both "[disabled]", ×505 in one document), sysctl, mkfs.bfs, llvm-size-18. Repeat-count of the shared description does not separate these from genuine runs (ffplay -h/-?/-help/--help, -loglevel/-v, ffmpeg -c/-codec) — several genuine aliases sit at the same count as the fabrications. Withdrawn from #97; only the evidence-anchored value recovery shipped. Needs an axis other than description equality.

2. Choices-block ownership beyond literal matches

#99 attaches a heading's choices only when the heading literally names the flag or contains its value_name as a word. Morphological variants stay unproven and render as before: automake's "Warning categories include:" belongs to -W, --warnings=CATEGORY ("categories" ≠ CATEGORY); cp/install/ln/mv's backup-control block. A stem/plural rule needs a fleet measurement of its false-positive cost before it can be admitted.

3. List rows naming independent options

ld's ten-name row and socat-mux's -b|-S|-t|-T|-l read as one multi-spelling entity because the row's own grammar says alias list; the tool means "any of these". No shape-level evidence distinguishes them from -h|--help. Accepted as a faithful reading; a fix needs evidence outside the row.

4. Wrapped-prose row boundary

zgrep, resolvconf, jpackage: a description that wraps onto a line starting with a dash-led word is read as the next row. Pre-existing; the C3 whitespace-continuation rules in #97 do not reach it.

5. Smaller items

• ffplay --help (11k lines) parses in ~3.3s in debug builds, over the corpus runner's 100ms advisory ceiling; non-failing.
• The corpus [contract] schema has no field asserting a flag's description text, so argfile rows become real flags: @<file> renders, searches, and copies (closes #93) #100's --target/--output description recovery is guarded only by the snapshot.
• is_value_spec_token accepts an all-uppercase prose word (--flag NOTE this does X) as a value name; documented in its tests, unobserved in the fleet.
• as-style =WORD placeholder-word choices (--foo=FILE|DIR) are still read as choices, not as alternative placeholders.

[Stiven-Gjekaj]

Hey, I'd love to contribute to this repo as I've started using it and it's been amazing. On your say so, I'd like to tackle this issue. Much appreciated for this lovely product.

[sadigaxund]

Hi @Stiven-Gjekaj, thank you for using and taking an interest to contribute!

Regarding this issue, two of its five items are done (the wrapped-prose row boundary shipped in #120) while the alias-run fold and the choices-block ownership items are still open. Most of the known broken tools live in corpus/: each one is a saved copy of a tool's --help text plus what we expect the parser to produce, and the ones we know we still get wrong are marked [xfail], "expected to fail", so the test suite tracks them until someone fixes them. I will try to surface some of them as issues here.

But there is also another way: run cargo xtask audit contribute. It draws a random sample of the tools on your own machine and opens the visual audit mode of mandible itself, mandible --review: each tool appears in actual TUI interface but modified so that you can mark (with notes) what you see as correct, incomplete, wrong or skip. Your verdicts are saved as you go, and when the sample is done the command prints the exact commands to commit them and open a small pull request yourself. Then if any broken part is detected you could try to fix that and PR the fix. However, make sure to read how to proceed to fix: save the tool's help text as a corpus fixture first, put the fix in the generic parser, run cargo nextest run and cargo xtask corpus, and check with a full-PATH sweep that no other tool lost anything. One PR per fix.

I'd start by reading CONTRIBUTING.md. Then, I know that AGENTS.md is good when you are using AI, however, it also contains proper steps and instructions. I've tried to keep it brief and clear. You don't really need to read much of the specs and other stuff and I will be double checking your PR anyways, in case you miss something. Just note that: if it will cost me more to fix the PR than doing it over, I will just drop it.

[Stiven-Gjekaj]

Thanks for the reply. I started with cargo xtask audit contribute and stopped before the first probe. Three findings, on macOS 26.6.2 arm64 at 0.7.0 (4c607d2).

audit contribute refuses on macOS

$ cargo xtask audit contribute --sample 20
GitHub login: Stiven-Gjekaj
Error: refusing to run a full-PATH sweep uncontained: namespace containment unavailable on this host (user=false, pid=false, mount=false) — refusing to run a full-PATH sweep uncontained

containment.rs implements the namespaces for Linux only. The #[cfg(not(target_os = "linux"))] twins at containment.rs:222 and containment.rs:321 report every namespace type unavailable. sweep_guard then refuses. --allow-uncontained is the only way through.

This closes the path CONTRIBUTING.md @2 recommends. That section names macOS, Fedora and Alpine as the biggest blind spot. A macOS user who follows it reaches a refusal.

More than the containment is absent on macOS

reap.rs:25 states it: "Linux only. Elsewhere this module is a no-op; the leak stands as the documented residual risk (spec @6 rule 8)." arm_subreaper is empty and reap_probe_descendants returns 0.

So an uncontained macOS sweep runs without the namespaces, without the canary tripwires, and without the descendant reap. The argv allowlist, the timeout, the process group kill, the 8 MiB cap, the sanitized environment and setsid all still apply. My PATH holds 1792 executables. I did not run the sweep.

A submission cannot record its platform

AuditMeta at mandible-core/src/audit.rs:910 holds seed and sample_size. The report header prints the same two fields. scripts/check_submissions.sh:45 accepts only <login>/<seed>.toml and <login>/<seed>-report.txt, so no third file can carry the condition.

A macOS submission and an Ubuntu submission look the same once merged. The pull request body is the only place left to state the platform. That is the fact that makes the submission worth having.

What do you want as a first pull request?

1. The macOS audit, run with --allow-uncontained, with the platform and the condition in the pull request body.
2. A macOS containment path in containment.rs, using sandbox-exec for the write containment the mount namespace gives on Linux. This unblocks every macOS contributor. It touches spec @6 and @8, so I will not start it without your ruling.
3. A platform field and a containment field on AuditMeta, small and separate from the other two.
4. One of the parser items in this issue instead.

I would rather not send 1792 uncontained probes on a machine I use every day. I will run it if you want the data and you accept the condition.

[sadigaxund]

Good catch and more importantly you are right about the privacy concern. I only recently added this audit flow and still figuring out the nits.

Note: Thank you for taking time to write above details, I'll read your report and handle in the morning

[sadigaxund]

@Stiven-Gjekaj Thanks for the thorough check, all three findings hold. Here is where each lands:

1. The audit: hold it for now. The full-PATH sweep is the problem, not macOS. I am changing audit contribute to draw tool names first and probe only the drawn twenty, so the sweep disappears on every platform and --allow-uncontained on macOS means twenty probes you can see listed, not 1792. Run it once that lands.
2. macOS containment via sandbox-exec: not now because it changes what "contained" means on one platform and touches the safety part of the design, so it needs a bit more to implement. After item 1 the exposure is small enough to wait.
3. Platform and containment fields on AuditMeta and in the report header: sure, and this is a good first PR if you want it. Small, separate, and your macOS audit will need it. Two fields, the report line, and the fixture that reads them.
4. If you prefer parser work, the choices-block ownership item in this issue (automake's "Warning categories include:" not attaching to -W) is the best scoped one. Before that rule can ship it has to be measured it has to go through different kind of PATH sweep. This is just to make sure that the new parsers fixes more than it touches, and break none. But you can also just implement the fix and its corpus fixture and green tests, and I run the sweep on my side.