qmk-rgb/cmd/qmk-rgb-tool/doc_examples_test.go

package main

import (
	"os"
	"strconv"
	"strings"
	"testing"

	"github.com/spf13/cobra"
	"github.com/spf13/pflag"
)

// Every example in the docs is a command a reader may type. Six of them were not:
// `brightness 160`, `color <hex>`, `speed 0`, `effect 46`, `effect none` and
// `effect rainbow` all predate the zone becoming the first argument, and each
// either fails at the argument count or is read as a channel named after the
// value. A broken example in a reference is worse than no example, so the
// documented command lines are checked against the arity the commands enforce.
//
// Both shapes a reader may copy are read: the lines of a fenced bash block, and
// the inline code spans in prose. Five of the six were in prose, so reading only
// the blocks would have missed them.
func TestDocumentedInvocationsMatchTheCommandArity(t *testing.T) {
	// The argument counts each command accepts, as withZoneArgs and zoneArgs
	// declare them. A command missing here is one that names no channel, so its
	// argument count is not this test's business.
	arity := map[string][2]int{
		"enable":     {1, 1},
		"disable":    {1, 1},
		"effect":     {1, 2},
		"brightness": {2, 2},
		"speed":      {2, 2},
		"color":      {2, 2},
		"info":       {0, 1},
	}

	takesValue := flagsThatTakeAValue(newRootCommand())
	seen := 0

	for _, path := range []string{
		"../../README.md",
		"../../AGENTS.md",
		"../../.claude/skills/qmk-rgb/SKILL.md",
	} {
		data, err := os.ReadFile(path)
		if err != nil {
			t.Errorf("read %s: %v", path, err)
			continue
		}
		for _, line := range documentedCommandLines(string(data)) {
			command, args := splitInvocation(line.text, takesValue)
			want, known := arity[command]
			// A span naming the command alone is prose about it, and a quoted error
			// message carries the command without being one.
			if !known || len(args) == 0 || isQuotedMessage(args) {
				continue
			}
			seen++

			if got := len(args); got < want[0] || got > want[1] {
				t.Errorf("%s:%d passes %s to `%s`, which takes %s: %q",
					path, line.no, plural(got), command, describeArity(want), line.text)
				continue
			}
			// Every one of these commands takes its zone first. Whether the first
			// argument is a placeholder or a real value, it has to be a channel:
			// `color <hex>` and `effect 46` both write the value where the zone goes,
			// and the command reads it as a channel named after it. A completion
			// example is the third thing entirely: what follows the command is a
			// keypress, not an argument.
			if isKeypress(args) {
				continue
			}
			if !namesTheZone(args[0]) {
				t.Errorf("%s:%d writes %q where `%s` takes its zone: %q",
					path, line.no, args[0], command, line.text)
			}
		}
	}

	// A checker that reads nothing proves nothing, and the fence handling is the
	// part most able to match everything by accident.
	if seen < 10 {
		t.Errorf("checked %d documented command lines, want enough to be worth having", seen)
	}
}

// commandLine is one documented command line, with a prompt, a path prefix and a
// trailing comment already stripped.
type commandLine struct {
	text string
	no   int
}

// documentedCommandLines returns every line the docs offer as something to run:
// the command lines of a fenced bash block, and the inline code spans of prose.
// Neither a `$` prompt nor a leading `./` is part of what the command is given, so
// both go.
func documentedCommandLines(body string) []commandLine {
	var out []commandLine
	inFence := false
	for i, raw := range strings.Split(body, "\n") {
		line := strings.TrimSpace(raw)
		if strings.HasPrefix(line, "```") {
			inFence = strings.Contains(line, "bash")
			continue
		}
		if inFence {
			if idx := strings.Index(line, "#"); idx >= 0 {
				line = strings.TrimSpace(line[:idx])
			}
			if stripped := stripPrompt(line); stripped != "" {
				out = append(out, commandLine{text: stripped, no: i + 1})
			}
			continue
		}
		for _, span := range inlineCodeSpans(raw) {
			if stripped := stripPrompt(span); stripped != "" {
				out = append(out, commandLine{text: stripped, no: i + 1})
			}
		}
	}
	return out
}

// stripPrompt removes a `$ ` prompt and a leading `./`, and leaves the rest alone.
// The binary's own name is left in place, because whether a line carries it says
// something: a block usually does and a prose span usually does not, and matching
// the command is what the caller does either way.
func stripPrompt(line string) string {
	line = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(line), "$ "))
	line = strings.TrimSpace(strings.TrimPrefix(line, "./"))
	return strings.TrimSpace(line)
}

// inlineCodeSpans returns the backtick-quoted spans of a prose line, which is
// where a documented command lives when it is not in a block. A double backtick
// span is skipped, because that is how a span containing a backtick is written
// and it is not an invocation.
func inlineCodeSpans(line string) []string {
	var out []string
	parts := strings.Split(line, "``")
	if len(parts) > 1 {
		parts = parts[:1]
	}
	parts = strings.Split(parts[0], "`")
	for i := 1; i < len(parts); i += 2 {
		if span := strings.TrimSpace(parts[i]); span != "" {
			out = append(out, span)
		}
	}
	return out
}

// flagsThatTakeAValue reads the persistent flags off the real command tree, so
// whether a flag swallows the word after it is answered by the flag's own
// declaration rather than by a list written here. Guessing is what made an earlier
// version of this file read `--json effect all` as the command `all`.
func flagsThatTakeAValue(root *cobra.Command) map[string]bool {
	out := map[string]bool{}
	root.PersistentFlags().VisitAll(func(f *pflag.Flag) {
		if f.NoOptDefVal == "" {
			out["--"+f.Name] = true
		}
	})
	return out
}

// splitInvocation returns the command a line invokes and the positional arguments
// it is given. The binary's own name goes first, because a line may carry a flag
// before the command: `--device 2 brightness logo 160`. A flag that carries a
// value consumes that word, and it is the flag that has to be the first word after
// the command, so `info --json` leaves `info` with no arguments. A redirection
// ends the arguments, so `completion bash > file` gives `completion` one.
func splitInvocation(line string, takesValue map[string]bool) (string, []string) {
	args := strings.Fields(line)
	if len(args) > 0 && args[0] == "qmk-rgb-tool" {
		args = args[1:]
	}
	for len(args) > 0 && isFlag(args[0]) {
		name, _, inline := strings.Cut(args[0], "=")
		args = args[1:]
		if !inline && takesValue[name] && len(args) > 0 {
			args = args[1:]
		}
	}
	if len(args) == 0 {
		return "", nil
	}

	command := args[0]
	args = args[1:]
	// A flag may also follow the command, and a flag is not an argument.
	for len(args) > 0 && isFlag(args[len(args)-1]) {
		args = args[:len(args)-1]
	}
	for i, a := range args {
		if strings.HasPrefix(a, ">") {
			args = args[:i]
			break
		}
	}
	return command, args
}

func isFlag(arg string) bool { return len(arg) > 1 && strings.HasPrefix(arg, "-") }

// isKeypress reports whether a documented line ends in `<TAB>`, which is how the
// docs write a shell completion example. The command is named, and what follows it
// is a key the reader presses rather than an argument they pass, so there is no
// arity to check.
func isKeypress(args []string) bool {
	return strings.Contains(strings.ToLower(strings.Join(args, " ")), "<tab")
}

// namesTheZone reports whether an argument is written as a zone. A usage form may
// spell it `<zone>`, or `[zone]` where the command reads without one. Otherwise it
// is a channel name: a QMK subsystem name, the word `all`, a comma separated list
// of them, or a board's own name from its definition file — of which the docs
// name only the Impact 80's, since that is the board the file in the repository
// describes.
//
// This is a list of names and not a resolver, and it is the reason a zone the docs
// do not know cannot be checked here: the check is here to catch a value written
// where a name belongs, not to enumerate every name a board may carry.
func namesTheZone(arg string) bool {
	// The brackets that mark a placeholder say nothing about what it is.
	stripped := strings.NewReplacer("<", "", ">", "", "[", "", "]", "").Replace(arg)
	lowered := strings.ToLower(stripped)
	for _, zone := range []string{"zone", "all", "backlight", "rgblight", "rgb_matrix", "audio", "led_matrix", "logo", "side"} {
		if strings.Contains(lowered, zone) {
			return true
		}
	}
	return false
}

// isQuotedMessage reports whether a span is an error message the docs quote rather
// than a command someone would run. The messages this tool emits are English, so
// they carry words a command line cannot: `effect off is not supported on
// backlight` names the command without being an invocation of it.
func isQuotedMessage(args []string) bool {
	joined := strings.Join(args, " ")
	return strings.Contains(joined, " is ") || strings.Contains(joined, " not ")
}

func describeArity(want [2]int) string {
	if want[0] == want[1] {
		return "exactly " + strconv.Itoa(want[0])
	}
	return strconv.Itoa(want[0]) + " to " + strconv.Itoa(want[1])
}

func plural(n int) string {
	if n == 1 {
		return "1 argument"
	}
	return strconv.Itoa(n) + " arguments"
}