docs(cli): README / AGENTS.md / CHANGELOG + CI parity test
Wire-contract documentation and the CI check that keeps it honest. * cli/README.md gains a verbatim --help block (top-level + subtrees), an Exit codes table covering 0/1/2/3/4/5/6/7/10/124/130, a "Status vs check" verb-pair subtable, and a "doc wait" paragraph spelling out the four exit codes (0 / 1 / 124 / 130). The api passthrough note trims storage provider out of the deep-config list now that kb create --storage-provider is a polished flag. * cli/AGENTS.md becomes the contributor guide: build/test, CRUD flag conventions, the status/check verb pattern, long-poll wait commands, the SetAgentHelp pattern, and a full Error code reference with 35 typed codes mapped to namespaces, exit codes, retryable / hint guidance. Reference section is bracketed by HTML markers so a CI parity test can keep it in sync with AllCodes(). * cli/internal/cmdutil/errors_doc_test.go enforces parity: every code in AllCodes() must appear in AGENTS.md inside the markers, and AGENTS.md must not reference codes that no longer exist. Fails CI if a new typed code is added without documentation. * CHANGELOG.md gets the v0.6 entry: BREAKING (--json / --no-stream / WEKNORA_SDK_DEBUG / kb create --name), Added (--format / --jq / doc wait / --log-level / kb-and-agent status & check / multi-id delete / api --paginate / MCP schema extension / SetAgentHelp / signal-aware ctx / kb create --storage-provider / new operation.* namespace), Changed (multi-id partial-failure exit code, doc upload FlagError, --log-level FlagError, multi-id stdout cleanup, README / AGENTS.md changes), with a Migration from v0.5 section walking every BREAKING through its v0.6 replacement.
This commit is contained in:
@@ -0,0 +1,48 @@
|
||||
package cmdutil
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// TestAllCodes_DocumentedInAGENTS verifies every typed code returned by
|
||||
// AllCodes() surfaces in cli/AGENTS.md "Error code reference" section
|
||||
// (delimited by ERROR_REFERENCE_START/END markers).
|
||||
//
|
||||
// Prevents drift: a contributor adding a new ErrorCode without updating
|
||||
// the doc fails this test, forcing the doc to stay current.
|
||||
func TestAllCodes_DocumentedInAGENTS(t *testing.T) {
|
||||
// From cli/internal/cmdutil/, go up two levels to find cli/AGENTS.md.
|
||||
docPath, err := filepath.Abs("../../AGENTS.md")
|
||||
if err != nil {
|
||||
t.Fatalf("abs: %v", err)
|
||||
}
|
||||
content, err := os.ReadFile(docPath)
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", docPath, err)
|
||||
}
|
||||
doc := string(content)
|
||||
|
||||
const startMarker = "<!-- ERROR_REFERENCE_START -->"
|
||||
const endMarker = "<!-- ERROR_REFERENCE_END -->"
|
||||
startIdx := strings.Index(doc, startMarker)
|
||||
endIdx := strings.Index(doc, endMarker)
|
||||
if startIdx == -1 || endIdx == -1 || endIdx <= startIdx {
|
||||
t.Fatalf("error-reference markers missing or malformed in %s:\n start=%d end=%d", docPath, startIdx, endIdx)
|
||||
}
|
||||
refSection := doc[startIdx:endIdx]
|
||||
|
||||
missing := []string{}
|
||||
for _, c := range AllCodes() {
|
||||
needle := "`" + string(c) + "`"
|
||||
if !strings.Contains(refSection, needle) {
|
||||
missing = append(missing, string(c))
|
||||
}
|
||||
}
|
||||
if len(missing) > 0 {
|
||||
t.Errorf("the following error codes are registered in AllCodes() but not listed in cli/AGENTS.md \"Error code reference\" section between the ERROR_REFERENCE markers:\n - %s\n\nAdd a row for each missing code to keep agent-facing docs in sync.",
|
||||
strings.Join(missing, "\n - "))
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user