Deprecate the ignored traversal flag

CHANGELOG.md

@@ -21,6 +21,12 @@ All notable changes to kage are recorded here. The format follows
 - `--max-pages` is documented as attempting at most N page renders; failed
   renders count toward the cap.
 
+### Deprecated
+
+- `--traversal` remains accepted for existing scripts but is now marked
+  deprecated because it was never read; crawls are always breadth-first. The
+  flag is planned for removal in the next minor release.
+
 ### Fixed
 
 - `--resume` picks an interrupted crawl back up instead of doing nothing ([#36](https://github.com/tamnd/kage/issues/36)).

cli/clone.go

@@ -71,7 +71,8 @@ func newCloneCmd() *cobra.Command {
 	fs.IntVar(&f.browserPages, "browser-pages", 4, "Chrome page-pool size")
 	fs.IntVarP(&f.maxPages, "max-pages", "p", 0, "attempt at most N page renders (0 = unlimited)")
 	fs.IntVarP(&f.maxDepth, "max-depth", "d", 0, "link-follow depth cap (0 = unlimited)")
-	fs.StringVar(&f.traversal, "traversal", "bfs", "frontier order: bfs or dfs")
+	fs.StringVar(&f.traversal, "traversal", "bfs", "frontier order (ignored; the crawl is always breadth-first)")
+	_ = fs.MarkDeprecated("traversal", "the crawl is always breadth-first; this flag was never read")
 	fs.Int64Var(&f.maxAssetMB, "max-asset-mb", 25, "skip assets larger than N MB (left on the live web)")
 	fs.BoolVar(&f.keepMedia, "keep-media", false, "download bulk media, installers, and PDFs instead of leaving them remote")
 	fs.StringSliceVar(&f.skipExt, "skip-ext", nil, "extra asset extensions to leave remote, e.g. .svg (repeatable)")

cli/clone_test.go

@@ -0,0 +1,20 @@
+package cli
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestTraversalFlagRemainsAcceptedButDeprecated(t *testing.T) {
+	cmd := newCloneCmd()
+	flag := cmd.Flags().Lookup("traversal")
+	if flag == nil {
+		t.Fatal("--traversal was removed; existing scripts must keep parsing")
+	}
+	if !strings.Contains(flag.Deprecated, "always breadth-first") {
+		t.Errorf("deprecation message = %q, want breadth-first explanation", flag.Deprecated)
+	}
+	if err := cmd.Flags().Set("traversal", "dfs"); err != nil {
+		t.Fatalf("legacy --traversal dfs no longer parses: %v", err)
+	}
+}

docs/content/reference/cli.md

@@ -40,7 +40,7 @@ images, and fonts, and writes a browsable mirror to `<out>/<host>/`.
 | `--scope-prefix` | | Only crawl the path prefix and its descendants, not similar path names |
 | `--subdomains` | `false` | Treat subdomains of the seed host as in scope |
 | `--exclude` | | Path prefixes to skip (repeatable); matches the path and its descendants, not substrings elsewhere |
-| `--traversal` | `bfs` | Frontier order: `bfs` or `dfs` |
+| `--traversal` | `bfs` | Deprecated and ignored; the crawl is always breadth-first |
 
 ### Politeness