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

package main

import (
	"os"
	"strings"
	"testing"
)

// README.md is the single source of truth for documented behaviour; agents are
// told to read it whole. AGENTS.md therefore carries discipline, not a second
// copy of the reference. Duplicated reference is what went stale: the
// `rgb <subcommand>` prefix survived in eleven lines of prose, and ledLayout was
// promised in AGENTS.md while the code never read it.
//
// These tests fail if the duplication creeps back.
func TestAgentsDocDoesNotDuplicateTheEffectCatalog(t *testing.T) {
	data, err := os.ReadFile("../../AGENTS.md")
	if err != nil {
		t.Fatalf("read AGENTS.md: %v", err)
	}
	body := string(data)

	// Effect names that exist only as catalog entries. The Discipline chapters
	// legitimately mention a few by name, so match a representative set of
	// obscure ones plus the literal range statements.
	for _, name := range []string{
		"jellybean_raindrops", "band_pinwheel_sat", "hue_pendulum",
		"starlight_dual_sat", "solid_reactive_multinexus", "riverflow",
		"multisplash",
	} {
		if strings.Contains(body, name) {
			t.Errorf("AGENTS.md lists the effect %q; the catalog comes live from `qmk-rgb-tool effect --list`", name)
		}
	}

	for _, rangeStmt := range []string{"ID 0–45 family", "ID 0-45 family", "IDs 0–45", "IDs 0-45"} {
		if strings.Contains(body, rangeStmt) {
			t.Errorf("AGENTS.md states %q; the per-zone catalog comes from `qmk-rgb-tool effect --list`", rangeStmt)
		}
	}
}

func TestAgentsDocDoesNotDuplicateTheCommandTable(t *testing.T) {
	data, err := os.ReadFile("../../AGENTS.md")
	if err != nil {
		t.Fatalf("read AGENTS.md: %v", err)
	}
	body := string(data)

	// A fenced block enumerating invocations is the duplicated CLI table.
	commands := []string{
		"qmk-rgb-tool effect breathing",
		"qmk-rgb-tool brightness <val>",
		"qmk-rgb-tool color <hex>",
		"qmk-rgb-tool speed <val>",
		"qmk-rgb-tool mode <index>",
	}
	for _, cmd := range commands {
		if strings.Contains(body, cmd) {
			t.Errorf("AGENTS.md lists the invocation %q; the command surface lives in README.md", cmd)
		}
	}
}

func TestAgentsDocTellsAgentsToReadTheReadme(t *testing.T) {
	data, err := os.ReadFile("../../AGENTS.md")
	if err != nil {
		t.Fatalf("read AGENTS.md: %v", err)
	}
	body := string(data)

	if !strings.Contains(body, "README.md") {
		t.Fatal("AGENTS.md never points at README.md, so nothing tells an agent to read the real reference")
	}

	// The instruction must be a directive, not a passing mention.
	lowered := strings.ToLower(body)
	directives := []string{"read it in full", "read it whole", "read it entirely"}
	found := false
	for _, directive := range directives {
		if strings.Contains(lowered, directive) {
			found = true
			break
		}
	}
	if !found {
		t.Errorf("AGENTS.md does not instruct the agent to read README.md in full; wanted one of %v", directives)
	}
}