(path string, idx int, ex Example, doc *Document, root *cobra.Command)
| 42 | } |
| 43 | |
| 44 | func validateExample(path string, idx int, ex Example, doc *Document, root *cobra.Command) []string { |
| 45 | tokens, err := shellSplit(ex.Cmd) |
| 46 | if err != nil { |
| 47 | return []string{fmt.Sprintf("%s example[%d]: cannot tokenize %q: %v", path, idx, ex.Cmd, err)} |
| 48 | } |
| 49 | if len(tokens) == 0 { |
| 50 | return []string{fmt.Sprintf("%s example[%d]: empty cmd string", path, idx)} |
| 51 | } |
| 52 | |
| 53 | // Token 0 should be the binary's name. Examples that begin with |
| 54 | // something else (e.g. `cat ~/foo.json | jq`) are documentation |
| 55 | // snippets showing related output, not pad invocations the |
| 56 | // validator can check. Skip them rather than fail — the drift |
| 57 | // contract is for pad-invocation drift specifically. |
| 58 | binary := root.Name() |
| 59 | if tokens[0] != binary { |
| 60 | return nil |
| 61 | } |
| 62 | |
| 63 | // Pass the full post-binary token stream to cobra's Find. Cobra |
| 64 | // knows each command's flag set and skips flag/value pairs while |
| 65 | // matching subcommand names — so examples that interleave flags |
| 66 | // with subcommands (e.g. `pad --workspace foo item create task`) |
| 67 | // resolve to `item create`, not the root. |
| 68 | target, _, ferr := root.Find(tokens[1:]) |
| 69 | if ferr != nil || target == nil { |
| 70 | return []string{fmt.Sprintf("%s example[%d]: command path doesn't resolve: %s", path, idx, ex.Cmd)} |
| 71 | } |
| 72 | |
| 73 | // Validate every --flag/-f against target's flag tree. |
| 74 | // Note: flags can appear before the subcommand path on cobra |
| 75 | // (e.g. `pad --workspace foo item create ...`), so scan all tokens. |
| 76 | var findings []string |
| 77 | skipNext := false |
| 78 | for _, t := range tokens[1:] { |
| 79 | if skipNext { |
| 80 | skipNext = false |
| 81 | continue |
| 82 | } |
| 83 | // Cobra treats a lone "--" as the flag terminator: every token |
| 84 | // after it is a positional argument, never a flag, even one that |
| 85 | // LOOKS like an unknown flag (e.g. `-- "-ship it"`). The scan must |
| 86 | // stop here too, before the dash-stripping below — continuing past |
| 87 | // it, as this used to, misread the terminated example's own |
| 88 | // leading-dash text as an unrecognized flag. A lone "-" (the stdin |
| 89 | // convention) is a different token and must NOT stop the scan; it |
| 90 | // falls through to the empty-name check below instead. |
| 91 | if t == "--" { |
| 92 | break |
| 93 | } |
| 94 | if !strings.HasPrefix(t, "-") { |
| 95 | continue |
| 96 | } |
| 97 | // Strip leading dashes and any =value suffix. |
| 98 | name := strings.TrimLeft(t, "-") |
| 99 | if eq := strings.IndexByte(name, '='); eq >= 0 { |
| 100 | name = name[:eq] |
| 101 | } |
no test coverage detected