feat: add skill command drift check (CI gate)

cmd/cmdexample_catalog_test.go

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"sort"
+	"strings"
+)
+
+// universalFlags are accepted by every command (cobra auto-injects help; the
+// root injects version). They are never reported as unknown.
+var universalFlags = map[string]bool{"--help": true, "-h": true, "--version": true}
+
+// catalog is the source-of-truth command catalog: command path -> accepted flag
+// tokens. A path is the command words WITHOUT the "lark-cli" root prefix, e.g.
+// "contact +search-user". The root command is the empty path "".
+type catalog struct {
+	flagsByPath map[string]map[string]bool
+	group       map[string]bool // paths that are parent groups (have subcommands)
+	sorted      []string        // cached sorted paths for suggestCommand; invalidated on addCommand
+}
+
+func newCatalog() *catalog {
+	return &catalog{
+		flagsByPath: map[string]map[string]bool{},
+		group:       map[string]bool{},
+	}
+}
+
+// setGroup records whether path is a parent group (has subcommands). Leftover
+// words after a group node are unknown subcommands; after a leaf they are
+// positionals (e.g. "api GET /path").
+func (c *catalog) setGroup(path string, isGroup bool) {
+	if isGroup {
+		c.group[path] = true
+	}
+}
+
+func (c *catalog) isGroup(path string) bool { return c.group[path] }
+
+// addCommand registers a command path and the flags it accepts. Repeated calls
+// for the same path union the flag sets. flags are full tokens ("--query", "-q").
+func (c *catalog) addCommand(path string, flags []string) {
+	set := c.flagsByPath[path]
+	if set == nil {
+		set = map[string]bool{}
+		c.flagsByPath[path] = set
+	}
+	for _, f := range flags {
+		set[f] = true
+	}
+	c.sorted = nil // invalidate cached suggestion list
+}
+
+func (c *catalog) hasCommand(path string) bool {
+	_, ok := c.flagsByPath[path]
+	return ok
+}
+
+// hasFlag reports whether flag is accepted by command path (universal flags
+// always pass).
+func (c *catalog) hasFlag(path, flag string) bool {
+	if universalFlags[flag] {
+		return true
+	}
+	set := c.flagsByPath[path]
+	return set[flag]
+}
+
+// longestPrefix returns the longest known command path that is a prefix of
+// words, plus how many words it consumed. This separates real subcommands from
+// trailing positionals (e.g. "api GET /path" resolves to "api"). When words is
+// empty it falls back to the root command. ok=false means not even the first
+// word names a command.
+func (c *catalog) longestPrefix(words []string) (path string, n int, ok bool) {
+	if len(words) == 0 {
+		if c.hasCommand("") {
+			return "", 0, true
+		}
+		return "", 0, false
+	}
+	for i := len(words); i >= 1; i-- {
+		cand := strings.Join(words[:i], " ")
+		if c.hasCommand(cand) {
+			return cand, i, true
+		}
+	}
+	return "", 0, false
+}
+
+// paths returns all known command paths, sorted.
+func (c *catalog) paths() []string {
+	out := make([]string, 0, len(c.flagsByPath))
+	for p := range c.flagsByPath {
+		out = append(out, p)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// suggestCommand returns the known command path closest to want (small edit
+// distance), for error hints. Returns "" when nothing is reasonably close.
+func (c *catalog) suggestCommand(want string) string {
+	if c.sorted == nil {
+		c.sorted = c.paths() // built once after the catalog is fully populated
+	}
+	return closest(want, c.sorted)
+}
+
+// suggestFlag returns the flag of path closest to flag, for error hints.
+func (c *catalog) suggestFlag(path, flag string) string {
+	set := c.flagsByPath[path]
+	cands := make([]string, 0, len(set))
+	for f := range set {
+		cands = append(cands, f)
+	}
+	sort.Strings(cands)
+	return closest(flag, cands)
+}
+
+// closest returns the candidate with the smallest Levenshtein distance to want,
+// but only if that distance is within a tolerance scaled to want's length
+// (avoids absurd suggestions).
+func closest(want string, cands []string) string {
+	best := ""
+	bestD := 1 << 30
+	for _, cand := range cands {
+		d := levenshtein(want, cand)
+		if d < bestD {
+			bestD, best = d, cand
+		}
+	}
+	tol := len(want)/2 + 1
+	if bestD > tol {
+		return ""
+	}
+	return best
+}
+
+func levenshtein(a, b string) int {
+	ra, rb := []rune(a), []rune(b)
+	prev := make([]int, len(rb)+1)
+	for j := range prev {
+		prev[j] = j
+	}
+	for i := 1; i <= len(ra); i++ {
+		cur := make([]int, len(rb)+1)
+		cur[0] = i
+		for j := 1; j <= len(rb); j++ {
+			cost := 1
+			if ra[i-1] == rb[j-1] {
+				cost = 0
+			}
+			cur[j] = min(prev[j]+1, cur[j-1]+1, prev[j-1]+cost)
+		}
+		prev = cur
+	}
+	return prev[len(rb)]
+}

cmd/cmdexample_check_test.go

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import "strings"
+
+// Finding kinds.
+const (
+	unknownCommand = "unknown_command"
+	unknownFlag    = "unknown_flag"
+)
+
+// finding is a single mismatch between an example command reference and the
+// catalog.
+type finding struct {
+	line    int
+	raw     string
+	kind    string // unknownCommand | unknownFlag
+	path    string // resolved command path (unknownFlag) or attempted path (unknownCommand)
+	flag    string // offending flag (unknownFlag only)
+	suggest string // nearest known command/flag, "" if none close
+}
+
+// checkRefs validates refs against cat and returns all mismatches in order.
+func checkRefs(cat *catalog, refs []ref) []finding {
+	var out []finding
+	for _, r := range refs {
+		path, n, ok := cat.longestPrefix(r.words)
+		if !ok {
+			attempted := strings.Join(r.words, " ")
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownCommand,
+				path: attempted, suggest: cat.suggestCommand(attempted),
+			})
+			continue
+		}
+		// Leftover words after a group node are an unknown subcommand (e.g. a
+		// mistyped method like "batch_modify_message"). After a leaf they are
+		// positionals (e.g. "api GET /path"), so only groups trigger this.
+		if n < len(r.words) && cat.isGroup(path) {
+			attempted := strings.Join(r.words, " ")
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownCommand,
+				path: attempted, suggest: cat.suggestCommand(attempted),
+			})
+			continue
+		}
+		for _, f := range r.flags {
+			if cat.hasFlag(path, f) {
+				continue
+			}
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownFlag,
+				path: path, flag: f, suggest: cat.suggestFlag(path, f),
+			})
+		}
+	}
+	return out
+}