feat(pkg): export Permutations from pkg/subenum (#197)

subenum.Permutations(seeds, words) wraps internal/permute.Generate, the
generator -permute already uses, so library callers can build a
second-pass candidate list without copying it. nil words selects the
CLI's built-in list. Adds tests, ExamplePermutations, a section in
docs/library.md and a CHANGELOG entry.

The Diff half of the issue is not done: the diff logic lives in package
main and its "removed"/"changed" semantics need decisions first.

Refs #197

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LpkeXSPwrzd7ZCuX3no7gD

Author: TMHSDigital

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `pkg/subenum` exports `Permutations(seeds, words []string) []string`, the candidate generator behind `-permute`: from names already found it returns the nearby variants (`api-dev`, `dev-api`, `dev.api`, `api2`), relative to the apex and ready to pass as a second scan's `Words`. `nil` words selects the CLI's built-in list. It sends no DNS queries (#197).
 - `-tui` pre-fills its form from the command line: `subenum -tui example.com -w big.txt -r resolvers.txt` opens with the domain, wordlist and resolver file filled in, over `SUBENUM_*`, config file and remembered values. Flags the form has no field for are named in a warning instead of being dropped silently; the form takes the first `-w`. The form gains **Resolver Pool** (`-r`) and **Rate/Resolver** (`-rate-per-resolver`) fields, remembered in `last.json`. After a scan, `r` restores the values just scanned rather than re-applying the launch flags over them (#195).
 - `-rate-per-resolver N` caps the DNS queries per second sent to each `-r` pool resolver, so a high global `-rate` no longer lands in uneven bursts on single members. Lookups go to resolvers with room first and wait only when every cap is spent; `-rate` still caps the total, and the stricter limit wins. The end-of-run resolver table and the report's `resolvers` entries gain a `throttled` count, and `pkg/subenum` gains `Config.RatePerResolver` (#196).
 - `-w` can be repeated to layer wordlists, for example a general list plus a target-specific one: `-w general.txt -w target.txt` reads both in order and scans an entry found in both only once (counted as a duplicate, as within one file). `-` stays valid as one of the entries. A `w` value from the config file or `SUBENUM_W` is replaced, not extended, by `-w` on the command line (#199).

docs/library.md

@@ -59,6 +59,20 @@ for ev := range events {
 
 Read the channel until it closes, or cancel `ctx`. Breaking out of the loop with a deferred `cancel()` is safe: once `ctx` is cancelled the scan stops without waiting for a reader, and its goroutines exit within about a second whether or not the channel is read. A consumer that keeps reading after cancelling still gets `KindDone` with the counts so far. While `ctx` is live, a consumer that stops reading pauses the scan once the buffer fills.
 
+## Permutations: second-pass candidates
+
+`Permutations` makes the candidates the CLI's `-permute` tries: from names a scan already found, the variants most likely to sit next to them (`api` suggests `api-dev`, `dev-api`, `dev.api`, `api2` and so on). Seeds and results are relative to the apex, like `Words`, so the output feeds a second scan directly. Pass `nil` words for the CLI's built-in list of environment, version and role names. It sends no DNS queries:
+
+```go
+seeds := []string{"api", "mail"} // api.example.com and mail.example.com were found
+more, _, err := subenum.Scan(ctx, subenum.Config{
+    Domain: "example.com",
+    Words:  subenum.Permutations(seeds, nil),
+})
+```
+
+The result is sorted and duplicate-free, and names that are not valid in DNS are left out.
+
 ## Configuration
 
 | Field | Default | What it does |

pkg/subenum/example_test.go

@@ -150,3 +150,20 @@ func ExampleConfig_recursive() {
 	// dev.example.com
 	// out of scope, never queried: 2
 }
+
+// Permutations suggests the names most likely to sit next to ones a scan
+// already found. Its output is relative to the apex, so it can feed the Words
+// of a second scan. Pass nil words for the CLI's built-in list.
+func ExamplePermutations() {
+	for _, name := range subenum.Permutations([]string{"api"}, []string{"dev"}) {
+		fmt.Println(name)
+	}
+
+	// Output:
+	// api-dev
+	// api1
+	// api2
+	// api3
+	// dev-api
+	// dev.api
+}

pkg/subenum/permutations_test.go

@@ -0,0 +1,41 @@
+package subenum_test
+
+import (
+	"slices"
+	"testing"
+
+	"github.com/TMHSDigital/subenum/pkg/subenum"
+)
+
+func TestPermutations(t *testing.T) {
+	got := subenum.Permutations([]string{"API.us.", "", "api.us"}, []string{"dev", "api"})
+	want := []string{"api-dev.us", "api1.us", "api2.us", "api3.us", "dev-api.us", "dev.api.us"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("Permutations = %q, want %q", got, want)
+	}
+}
+
+func TestPermutationsNilWordsUsesBuiltinList(t *testing.T) {
+	got := subenum.Permutations([]string{"api"}, nil)
+	for _, name := range []string{"api-staging", "prod-api", "dev.api", "api-v2", "api2"} {
+		if !slices.Contains(got, name) {
+			t.Errorf("Permutations(nil words) is missing %q", name)
+		}
+	}
+	if !slices.IsSorted(got) || len(slices.Compact(slices.Clone(got))) != len(got) {
+		t.Errorf("Permutations(nil words) is not sorted and duplicate-free: %q", got)
+	}
+	if empty := subenum.Permutations([]string{"api"}, []string{}); len(empty) == 0 || slices.Contains(empty, "api-dev") {
+		t.Errorf("Permutations(empty words) = %q, want only numbered variants", empty)
+	}
+}
+
+func TestPermutationsDropsInvalidLabels(t *testing.T) {
+	// "-x" makes "-x.api", whose first label starts with a hyphen.
+	if got := subenum.Permutations([]string{"api"}, []string{"-x"}); slices.Contains(got, "-x.api") {
+		t.Errorf("Permutations kept the invalid name -x.api: %q", got)
+	}
+	if got := subenum.Permutations(nil, nil); len(got) != 0 {
+		t.Errorf("Permutations(nil, nil) = %q, want none", got)
+	}
+}

pkg/subenum/subenum.go

@@ -27,6 +27,7 @@ import (
 
 	"github.com/TMHSDigital/subenum/data"
 	"github.com/TMHSDigital/subenum/internal/dns"
+	"github.com/TMHSDigital/subenum/internal/permute"
 	"github.com/TMHSDigital/subenum/internal/scan"
 	"github.com/TMHSDigital/subenum/internal/validate"
 	"github.com/TMHSDigital/subenum/internal/wordlist"
@@ -343,6 +344,22 @@ var defaultWords = sync.OnceValue(func() []string {
 	return words
 })
 
+// Permutations returns second-pass candidates for names a scan already found,
+// the same ones the CLI's -permute tries: api suggests api-dev, dev-api,
+// dev.api, api2 and so on. Each seed is a name relative to the apex, such as
+// "api" for api.example.com or "api.us" for api.us.example.com; its leftmost
+// label is permuted and the rest kept. words are combined with each seed
+// label; nil selects the CLI's built-in list of environment, version and role
+// names. Candidates that are not valid DNS names are left out. The result is
+// relative to the apex, like Config.Words, sorted and duplicate-free, so it
+// can be passed as the Words of a follow-up scan. It sends no DNS queries.
+func Permutations(seeds, words []string) []string {
+	if words == nil {
+		words = permute.Words
+	}
+	return permute.Generate(seeds, words, nil)
+}
+
 // doneGrace is how long Run's forwarder waits to hand over the final event
 // after ctx is cancelled, when the caller may have stopped reading.
 var doneGrace atomic.Int64 // a time.Duration; atomic so tests can change it while forwarders run