feat: add support for user-doc-based help routing and manifest generation #6884
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| package helpdocs | ||
|
|
||
| import ( | ||
| _ "embed" | ||
| "regexp" | ||
| "strings" | ||
| ) | ||
|
|
||
| //go:embed manifest.txt | ||
| var manifest string | ||
|
|
||
| var docFiles map[string]struct{} | ||
|
|
||
| var nonDocChars = regexp.MustCompile(`[^a-zA-Z0-9-]`) | ||
|
|
||
| func init() { | ||
| docFiles = manifestFileSet(manifest) | ||
| } | ||
|
|
||
| // manifestFileSet builds the doc filename set from manifest text. | ||
| // Trims trailing carriage returns so CRLF-checked-out manifests still match lookups. | ||
| func manifestFileSet(manifestText string) map[string]struct{} { | ||
| files := make(map[string]struct{}) | ||
| for _, line := range manifestLines(manifestText) { | ||
| files[line] = struct{}{} | ||
| } | ||
| return files | ||
| } | ||
|
|
||
| func manifestLines(manifestText string) []string { | ||
| var lines []string | ||
| for _, line := range strings.Split(strings.TrimSpace(manifestText), "\n") { | ||
| line = strings.TrimSuffix(line, "\r") | ||
| if line != "" { | ||
| lines = append(lines, line) | ||
| } | ||
| } | ||
| return lines | ||
| } | ||
|
|
||
| // helpFileName mirrors src/cli/commands/help/index.ts join + cleanse. | ||
| func helpFileName(segments []string) string { | ||
| joined := strings.Join(segments, "-") | ||
| cleaned := nonDocChars.ReplaceAllString(joined, "") | ||
| return cleaned + ".md" | ||
| } | ||
|
|
||
| // HasUserDoc reports whether legacy user-doc help should be shown for command segments. | ||
| // Empty segments → true (top-level README via legacy help). | ||
| // Non-empty segments → true only if a matching .md exists during walk-back (README excluded). | ||
| func HasUserDoc(segments []string) bool { | ||
| return hasUserDoc(docFiles, segments) | ||
| } | ||
|
|
||
| func hasUserDoc(files map[string]struct{}, segments []string) bool { | ||
| if len(segments) == 0 { | ||
| return true | ||
| } | ||
| if len(files) == 0 { | ||
| // Missing or empty manifest at build time: prefer legacy help lookup. | ||
| return true | ||
| } | ||
| args := append([]string(nil), segments...) | ||
| for len(args) > 0 { | ||
| if _, ok := files[helpFileName(args)]; ok { | ||
| return true | ||
| } | ||
| args = args[:len(args)-1] | ||
| } | ||
| return false | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| package helpdocs | ||
|
|
||
| import ( | ||
| "os" | ||
| "path/filepath" | ||
| "sort" | ||
| "strings" | ||
| "testing" | ||
|
|
||
| "github.com/stretchr/testify/assert" | ||
| "github.com/stretchr/testify/require" | ||
| ) | ||
|
|
||
| func testDocFiles() map[string]struct{} { | ||
| names := []string{ | ||
| "README.md", | ||
| "test.md", | ||
| "container.md", | ||
| "container-test.md", | ||
| "iac-describe.md", | ||
| "redteam.md", | ||
| } | ||
| files := make(map[string]struct{}, len(names)) | ||
| for _, name := range names { | ||
| files[name] = struct{}{} | ||
| } | ||
| return files | ||
| } | ||
|
|
||
| func Test_helpFileName(t *testing.T) { | ||
| assert.Equal(t, "container-test.md", helpFileName([]string{"container", "test"})) | ||
| assert.Equal(t, "iac-describe.md", helpFileName([]string{"iac", "describe"})) | ||
| assert.Equal(t, "secrets-test.md", helpFileName([]string{"secrets", "test"})) | ||
| } | ||
|
|
||
| func Test_hasUserDoc(t *testing.T) { | ||
| files := testDocFiles() | ||
|
|
||
| tests := map[string]struct { | ||
| segments []string | ||
| want bool | ||
| }{ | ||
| "empty uses readme path": {segments: []string{}, want: true}, | ||
| "test command": {segments: []string{"test"}, want: true}, | ||
| "container test subcommand": {segments: []string{"container", "test"}, want: true}, | ||
| "iac describe subcommand": {segments: []string{"iac", "describe"}, want: true}, | ||
| "unknown command": {segments: []string{"rainmaker"}, want: false}, | ||
| "undocumented secrets test": {segments: []string{"secrets", "test"}, want: false}, | ||
| "redteam setup walks back to parent": {segments: []string{"redteam", "setup"}, want: true}, | ||
| "undocumented agent-scan": {segments: []string{"agent-scan"}, want: false}, | ||
| } | ||
|
|
||
| for name, tc := range tests { | ||
| t.Run(name, func(t *testing.T) { | ||
| assert.Equal(t, tc.want, hasUserDoc(files, tc.segments)) | ||
| }) | ||
| } | ||
| } | ||
|
|
||
| func Test_HasUserDoc_usesEmbeddedManifest(t *testing.T) { | ||
| assert.True(t, HasUserDoc([]string{"test"})) | ||
| assert.NotEmpty(t, docFiles) | ||
| } | ||
|
|
||
| func Test_manifestFileSet_stripsCRLFLineEndings(t *testing.T) { | ||
| files := manifestFileSet("test.md\r\ncontainer-test.md\r\n") | ||
|
|
||
| assert.True(t, hasUserDoc(files, []string{"test"})) | ||
| assert.True(t, hasUserDoc(files, []string{"container", "test"})) | ||
| assert.False(t, hasUserDoc(files, []string{"rainmaker"})) | ||
| } | ||
|
|
||
| func Test_manifestMatchesHelpCLICommands(t *testing.T) { | ||
| helpDir := filepath.Join("..", "..", "..", "help", "cli-commands") | ||
| entries, err := os.ReadDir(helpDir) | ||
| require.NoError(t, err, "help/cli-commands must exist; run from repo root via go test ./pkg/helpdocs") | ||
|
|
||
| var fromDisk []string | ||
| for _, entry := range entries { | ||
| if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".md") { | ||
| continue | ||
| } | ||
| fromDisk = append(fromDisk, entry.Name()) | ||
| } | ||
| sort.Strings(fromDisk) | ||
|
|
||
| fromManifest := manifestEntries() | ||
| assert.Equal(t, fromDisk, fromManifest, | ||
| "embedded manifest.txt is out of sync with help/cli-commands; run: make -C cliv2 helpdocs-manifest") | ||
| } | ||
|
|
||
| func manifestEntries() []string { | ||
| entries := manifestLines(manifest) | ||
| sort.Strings(entries) | ||
| return entries | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| README.md | ||
| ai-red-teaming.md | ||
| aibom-test.md | ||
| aibom.md | ||
| apps.md | ||
| auth.md | ||
| code-test.md | ||
| code.md | ||
| config-environment.md | ||
| config.md | ||
| container-monitor.md | ||
| container-sbom.md | ||
| container-test.md | ||
| container.md | ||
| iac-capture.md | ||
| iac-describe.md | ||
| iac-report.md | ||
| iac-rules-init.md | ||
| iac-rules-push.md | ||
| iac-rules-test.md | ||
| iac-test.md | ||
| iac-update-exclude-policy.md | ||
| iac.md | ||
| ignore.md | ||
| log4shell.md | ||
| monitor.md | ||
| policy.md | ||
| redteam.md | ||
| sbom-monitor.md | ||
| sbom-test.md | ||
| sbom.md | ||
| test.md |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd prefer the other way around, that the code defines the public website docs, but I guess that's just preference.