From d1e5f10039c8f80ab807953eab2cf3665693a70e Mon Sep 17 00:00:00 2001
From: agra <alex@swipelab.co>
Date: Thu, 4 Jun 2026 07:38:57 +0300
Subject: [PATCH] F3.2: assert Diag (token,index) for all cli.parse error cases

Extend example 0717 to pin the offending token VIEW and its args index
for every failure the parser's Diag populates: unknown-command,
unknown-group, too-few-args, missing-value, value-eats-flag, and the
missing-required index. Closes the test-coverage gap flagged in review;
cli.sx parser logic unchanged.
---
 examples/0717-modules-cli-parse.sx            | 39 +++++++++++++++++--
 .../expected/0717-modules-cli-parse.stdout    | 11 ++++++
 2 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/examples/0717-modules-cli-parse.sx b/examples/0717-modules-cli-parse.sx
index ba9c2a0..e21e416 100644
--- a/examples/0717-modules-cli-parse.sx
+++ b/examples/0717-modules-cli-parse.sx
@@ -121,16 +121,49 @@ main :: () -> ! {
     report("err-value-eats-flag", raises(a_value_eats,    cmds, error.MissingValue));
     report("err-missing-req",     raises(a_missing_req,   cmds, error.MissingRequired));
 
-    // ── 8. Diag names the offending token on the error path ──────────
+    // ── 8. Diag pins the offending (token, index) for EVERY error case ─
+    // Each failure records the exact offending token (a VIEW into `args`,
+    // except a missing-required names the matched spec's flag name) plus
+    // its `args` index, so a caller can report which token failed. An
+    // unknown (group, command) PAIR — group wrong OR command wrong — pins
+    // the COMMAND token at index 1, since the pair as a whole is what
+    // failed to match; a missing-required uses index -1 (the token is a
+    // flag name, not an `args` slot).
     de : Diag = .{};
     _, ue := parse(a_unknown_flag, cmds, @de);
-    report("diag-flag-tag",   ue == error.UnknownFlag);
-    report("diag-flag-token", de.token == "--nope" and de.index == 4);
+    report("diag-flag-tag",     ue == error.UnknownFlag);
+    report("diag-flag-token",   de.token == "--nope" and de.index == 4);
+
+    dc : Diag = .{};
+    _, ce := parse(a_unknown_cmd, cmds, @dc);
+    report("diag-cmd-tag",      ce == error.UnknownCommand);
+    report("diag-cmd-token",    dc.token == "deploy" and dc.index == 1);
+
+    dg : Diag = .{};
+    _, ge := parse(a_unknown_group, cmds, @dg);
+    report("diag-group-tag",    ge == error.UnknownCommand);
+    report("diag-group-token",  dg.token == "publish" and dg.index == 1);
+
+    df : Diag = .{};
+    _, fe := parse(a_too_few, cmds, @df);
+    report("diag-too-few-tag",   fe == error.UnknownCommand);
+    report("diag-too-few-token", df.token == "ci" and df.index == 0);
+
+    dv : Diag = .{};
+    _, ve := parse(a_missing_value, cmds, @dv);
+    report("diag-missing-value-tag",   ve == error.MissingValue);
+    report("diag-missing-value-token", dv.token == "--out" and dv.index == 2);
+
+    dz : Diag = .{};
+    _, ze := parse(a_value_eats, cmds, @dz);
+    report("diag-value-eats-tag",   ze == error.MissingValue);
+    report("diag-value-eats-token", dz.token == "--out" and dz.index == 2);
 
     dm : Diag = .{};
     _, me := parse(a_missing_req, cmds, @dm);
     report("diag-req-tag",    me == error.MissingRequired);
     report("diag-req-token",  dm.token == "out");
+    report("diag-req-index",  dm.index == -1);
 
     print("=== DONE ===\n");
     return;
diff --git a/examples/expected/0717-modules-cli-parse.stdout b/examples/expected/0717-modules-cli-parse.stdout
index ab06f38..c658a4c 100644
--- a/examples/expected/0717-modules-cli-parse.stdout
+++ b/examples/expected/0717-modules-cli-parse.stdout
@@ -28,6 +28,17 @@ err-value-eats-flag: ok
 err-missing-req: ok
 diag-flag-tag: ok
 diag-flag-token: ok
+diag-cmd-tag: ok
+diag-cmd-token: ok
+diag-group-tag: ok
+diag-group-token: ok
+diag-too-few-tag: ok
+diag-too-few-token: ok
+diag-missing-value-tag: ok
+diag-missing-value-token: ok
+diag-value-eats-tag: ok
+diag-value-eats-token: ok
 diag-req-tag: ok
 diag-req-token: ok
+diag-req-index: ok
 === DONE ===