feeds: subscription audit command (per-feed volume + star stats)

GET /v1/feeds + feed_id entries filter in the client, one cheap volume
probe per feed over a --days window, star stats joined from labels.jsonl
by feed id, category column, --min-per-day/--min-seen filters. Read-only;
justfile recipe with one-line doc comments throughout.

2 files changed, 463 insertions, 0 deletions

diff --git a/cmds/feeds.go b/cmds/feeds.go
new file mode 100644
index 0000000..48d07de
--- /dev/null
+++ b/cmds/feeds.go
@@ -0,0 +1,185 @@
+// Feeds command: subscription pruning audit. Lists every subscribed feed
+// with its entry volume over a recent window (one cheap /v1/entries probe
+// per feed: limit=1, read only the total) joined with star stats from
+// labels.jsonl, so "loud" and "valuable to me" sit in the same table.
+// Read-only — it never writes to Miniflux; unsubscribing stays a human
+// action in the UI.
+//
+// The two columns have different denominators on purpose: volume comes
+// from the API (everything published in the window), stars come from
+// labels.jsonl (the sample export happened to capture, refreshed only when
+// export runs). Star rate is therefore a heuristic, and feeds with no
+// label rows render "-" — never confuse "no data" with a 0% rate.
+package cmds
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"sort"
+	"time"
+
+	"fluxrec/core"
+	"fluxrec/miniflux"
+)
+
+type FeedsCommand struct {
+	Days      int
+	Labels    string
+	MinPerDay float64
+	MinSeen   int
+}
+
+func (c *FeedsCommand) Name() string { return "feeds" }
+
+func (c *FeedsCommand) Init(args []string) error {
+	fs := flag.NewFlagSet(c.Name(), flag.ContinueOnError)
+	fs.Usage = func() {
+		fmt.Fprint(fs.Output(), `Usage: fluxrec feeds [flags]
+
+Print one row per subscribed feed: entry volume over the window (from the
+API) plus stars seen in labels.jsonl, sorted loudest first. For spotting
+dailies and high-volume feeds worth pruning. Read-only: nothing is
+written to Miniflux.
+
+Filter units differ on purpose: volume scales with the window, so its
+threshold is per-day (window-invariant); "seen" counts label rows, which
+accumulate over export history rather than the window, so its threshold
+is an absolute sample size.
+`)
+		fs.PrintDefaults()
+	}
+	fs.IntVar(&c.Days, "days", 180, "Count entries published within this many days")
+	fs.StringVar(&c.Labels, "labels", "labels.jsonl", "Path to labels.jsonl for star stats (empty = volume columns only)")
+	fs.Float64Var(&c.MinPerDay, "min-per-day", 0.05, "Only show feeds averaging at least this many entries/day (0 = all; default hides dead/dormant feeds)")
+	fs.IntVar(&c.MinSeen, "min-seen", 0, "Only show feeds with at least this many labeled rows (0 = all; hides '-' rows)")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	if c.Days < 1 {
+		return fmt.Errorf("--days must be >= 1, got %d", c.Days)
+	}
+	if c.MinPerDay < 0 {
+		return fmt.Errorf("--min-per-day must be >= 0, got %g", c.MinPerDay)
+	}
+	if c.MinSeen < 0 {
+		return fmt.Errorf("--min-seen must be >= 0, got %d", c.MinSeen)
+	}
+	return nil
+}
+
+// feedRow is one line of the audit table.
+type feedRow struct {
+	feed   miniflux.FeedInfo
+	volume int  // entries in the window (API total)
+	seen   int  // labeled rows for this feed (sample, not all entries)
+	stars  int  // of those, the positives
+	hasLbl bool // any rows at all — distinguishes "no data" from "0%"
+}
+
+func (c *FeedsCommand) Run(stdin io.Reader, stdout io.Writer) error {
+	cfg, err := miniflux.ConfigFromEnv()
+	if err != nil {
+		return err
+	}
+	client := miniflux.NewClient(cfg)
+
+	feeds, err := client.Feeds()
+	if err != nil {
+		return err
+	}
+
+	// Star stats per feed, joined by feed ID so renames are harmless.
+	// A missing labels file is not an error: a fresh checkout runs the
+	// audit volume-only.
+	stats := map[int64]*feedRow{}
+	if c.Labels != "" {
+		rows, err := core.ReadLabels(c.Labels)
+		if err != nil && !os.IsNotExist(err) {
+			return fmt.Errorf("reading labels: %w", err)
+		}
+		for _, r := range rows {
+			s := stats[r.FeedID]
+			if s == nil {
+				s = &feedRow{}
+				stats[r.FeedID] = s
+			}
+			s.seen++
+			if r.Label == core.LabelPos {
+				s.stars++
+			}
+			s.hasLbl = true
+		}
+	}
+
+	cutoff := time.Now().Add(-time.Duration(c.Days) * 24 * time.Hour).Unix()
+	table := make([]feedRow, 0, len(feeds))
+	for _, f := range feeds {
+		vol, err := c.feedVolume(client, f.ID, cutoff)
+		if err != nil {
+			return err
+		}
+		row := feedRow{feed: f, volume: vol}
+		if s := stats[f.ID]; s != nil {
+			row.seen, row.stars, row.hasLbl = s.seen, s.stars, s.hasLbl
+		}
+		table = append(table, row)
+	}
+
+	sort.SliceStable(table, func(i, j int) bool {
+		if table[i].volume == table[j].volume {
+			return table[i].feed.ID < table[j].feed.ID
+		}
+		return table[i].volume > table[j].volume
+	})
+
+	fmt.Fprintf(stdout, "%-6s %-36s %-16s %6s %6s   %6s %6s %6s\n", "id", "feed", "category", "days", "/day", "stars", "seen", "rate")
+	shown := 0
+	for _, r := range table {
+		perDay := float64(r.volume) / float64(c.Days)
+		if perDay < c.MinPerDay || r.seen < c.MinSeen {
+			continue
+		}
+		shown++
+		stars, seen, rate := "-", "-", "-"
+		if r.hasLbl {
+			stars = fmt.Sprint(r.stars)
+			seen = fmt.Sprint(r.seen)
+			rate = fmt.Sprintf("%.0f%%", 100*float64(r.stars)/float64(r.seen))
+		}
+		disabled := ""
+		if r.feed.Disabled {
+			disabled = " (disabled)"
+		}
+		fmt.Fprintf(stdout, "%-6d %-36s %-16s %6d %6.1f   %6s %6s %6s%s\n",
+			r.feed.ID, clip(r.feed.Title, 36), clip(r.feed.Category.Title, 16),
+			r.volume, perDay, stars, seen, rate, disabled)
+	}
+	fmt.Fprintf(stdout, "feeds: showing %d of %d subscriptions, window %d days; star stats from %s (sample — export refreshes it)\n",
+		shown, len(table), c.Days, c.Labels)
+	return nil
+}
+
+// clip shortens s to at most n runes, ending a truncated string with an
+// ellipsis, so one over-long title can't break the table's alignment.
+func clip(s string, n int) string {
+	r := []rune(s)
+	if len(r) <= n {
+		return s
+	}
+	if n <= 1 {
+		return string(r[:n])
+	}
+	return string(r[:n-1]) + "…"
+}
+
+// feedVolume counts entries published at or after cutoff for one feed via
+// a limit=1 probe — the cheap way to read EntrySet.Total.
+func (c *FeedsCommand) feedVolume(client *miniflux.Client, feedID int64, cutoff int64) (int, error) {
+	set, err := client.Entries(miniflux.Filters{FeedID: feedID, PublishedAfter: cutoff, Limit: 1})
+	if err != nil {
+		return 0, fmt.Errorf("counting feed %d: %w", feedID, err)
+	}
+	return set.Total, nil
+}
diff --git a/cmds/feeds_test.go b/cmds/feeds_test.go
new file mode 100644
index 0000000..60151cc
--- /dev/null
+++ b/cmds/feeds_test.go
@@ -0,0 +1,278 @@
+// Test for `fluxrec feeds` against an httptest fake Miniflux: rows are
+// sorted loudest-first, label stats join by feed ID, and a feed with no
+// label rows renders "-" rather than a fake 0% rate.
+package cmds
+
+import (
+	"bytes"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"fluxrec/core"
+)
+
+// feedsFake serves three feeds and per-feed entry counts keyed by the
+// feed_id query param, honoring published_after like pagedServer does.
+type feedsFake struct {
+	feedsJSON string
+	pool      map[int64][]testEntry // feed ID -> entries
+	queries   []string
+}
+
+func (f *feedsFake) handler() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		f.queries = append(f.queries, r.URL.Path+"?"+r.URL.RawQuery)
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path == "/v1/feeds" {
+			fmt.Fprint(w, f.feedsJSON)
+			return
+		}
+		q := r.URL.Query()
+		fid, _ := strconv.ParseInt(q.Get("feed_id"), 10, 64)
+		pool := f.pool[fid]
+		if pa, _ := strconv.ParseInt(q.Get("published_after"), 10, 64); pa > 0 {
+			cutoff := time.Unix(pa, 0)
+			filtered := pool[:0:0]
+			for _, e := range pool {
+				if !e.PublishedAt.Before(cutoff) {
+					filtered = append(filtered, e)
+				}
+			}
+			pool = filtered
+		}
+		limit, _ := strconv.Atoi(q.Get("limit"))
+		if limit <= 0 {
+			limit = len(pool)
+		}
+		if limit > len(pool) {
+			limit = len(pool)
+		}
+		fmt.Fprint(w, entriesJSON(len(pool), pool[:limit]))
+	}
+}
+
+func TestFeedsAudit(t *testing.T) {
+	now := time.Now()
+	fresh := func(entries []testEntry) []testEntry {
+		for i := range entries {
+			entries[i].PublishedAt = now.Add(-24 * time.Hour)
+		}
+		return entries
+	}
+	fake := &feedsFake{
+		feedsJSON: `[
+		  {"id": 1, "title": "Quiet Blog", "site_url": "https://quiet.example", "disabled": false,
+		   "category": {"id": 10, "title": "Blogs"}},
+		  {"id": 2, "title": "Firehose Daily", "site_url": "https://fire.example", "disabled": false,
+		   "category": {"id": 11, "title": "Flood"}},
+		  {"id": 3, "title": "New Sub", "site_url": "https://new.example", "disabled": false,
+		   "category": {"id": 10, "title": "Blogs"}}
+		]`,
+		pool: map[int64][]testEntry{
+			1: fresh(makeEntries(2, 100, false, 1)),
+			2: fresh(makeEntries(90, 200, false, 2)),
+			3: fresh(makeEntries(4, 300, false, 3)),
+		},
+	}
+	srv := httptest.NewServer(fake.handler())
+	defer srv.Close()
+	t.Setenv("MINIFLUX_URL", srv.URL)
+	t.Setenv("MINIFLUX_TOKEN", "test-token")
+
+	dir := t.TempDir()
+	labelsPath := filepath.Join(dir, "labels.jsonl")
+	if err := core.AppendLabels(labelsPath, []core.LabelRow{
+		{EntryID: 1, URL: "https://quiet.example/a", Title: "A", FeedID: 1, FeedTitle: "Quiet Blog", Label: core.LabelPos, CapturedAt: now},
+		{EntryID: 2, URL: "https://quiet.example/b", Title: "B", FeedID: 1, FeedTitle: "Quiet Blog", Label: core.LabelNeg, CapturedAt: now},
+		{EntryID: 3, URL: "https://fire.example/c", Title: "C", FeedID: 2, FeedTitle: "Firehose Daily", Label: core.LabelNeg, CapturedAt: now},
+	}); err != nil {
+		t.Fatalf("AppendLabels: %v", err)
+	}
+
+	cmd := &FeedsCommand{Days: 30, Labels: labelsPath}
+	var out bytes.Buffer
+	if err := cmd.Run(nil, &out); err != nil {
+		t.Fatalf("feeds: %v", err)
+	}
+	got := out.String()
+
+	// Sorted by volume: Firehose (90) before New Sub (4) before Quiet (2).
+	fi, ni, qi := strings.Index(got, "Firehose Daily"), strings.Index(got, "New Sub"), strings.Index(got, "Quiet Blog")
+	if fi < 0 || ni < 0 || qi < 0 {
+		t.Fatalf("output missing a feed row:\n%s", got)
+	}
+	if !(fi < ni && ni < qi) {
+		t.Errorf("rows not sorted by volume desc:\n%s", got)
+	}
+
+	// Label stats joined by feed ID: Quiet = 1/2 (50%), Firehose = 0/1 (0%).
+	if !strings.Contains(got, "50%") {
+		t.Errorf("Quiet Blog rate should be 50%%:\n%s", got)
+	}
+
+	// New Sub has no label rows: "-" placeholders, not a bogus 0%.
+	for _, line := range strings.Split(got, "\n") {
+		if strings.Contains(line, "New Sub") && !strings.Contains(line, "-") {
+			t.Errorf("New Sub should render '-' for missing label stats: %q", line)
+		}
+	}
+
+	// Per-feed day's rate: Firehose = 90/30 = 3.0/day.
+	if !strings.Contains(got, "3.0") {
+		t.Errorf("Firehose per-day rate missing:\n%s", got)
+	}
+
+	// Categories render next to their feeds.
+	for _, line := range strings.Split(got, "\n") {
+		if strings.Contains(line, "Firehose Daily") && !strings.Contains(line, "Flood") {
+			t.Errorf("Firehose row missing its category: %q", line)
+		}
+		if strings.Contains(line, "Quiet Blog") && !strings.Contains(line, "Blogs") {
+			t.Errorf("Quiet Blog row missing its category: %q", line)
+		}
+	}
+
+	// Unfiltered run shows all three feeds.
+	if !strings.Contains(got, "showing 3 of 3 subscriptions") {
+		t.Errorf("footer should count all feeds when unfiltered:\n%s", got)
+	}
+
+	// One /v1/feeds call plus one volume probe per feed, each carrying
+	// feed_id and published_after.
+	if len(fake.queries) != 4 {
+		t.Fatalf("expected 4 API calls, got %d: %v", len(fake.queries), fake.queries)
+	}
+	for _, q := range fake.queries[1:] {
+		if !strings.Contains(q, "feed_id=") || !strings.Contains(q, "published_after=") {
+			t.Errorf("volume probe missing filters: %q", q)
+		}
+	}
+}
+
+// Filters: --min-per-day keeps only the firehose (volume scales with the
+// window, so its threshold is per-day); --min-seen keeps only the
+// well-sampled feed (label rows accumulate over export history, so its
+// threshold is absolute).
+func TestFeedsFilters(t *testing.T) {
+	now := time.Now()
+	fresh := func(entries []testEntry) []testEntry {
+		for i := range entries {
+			entries[i].PublishedAt = now.Add(-24 * time.Hour)
+		}
+		return entries
+	}
+	newServer := func(t *testing.T) *httptest.Server {
+		t.Helper()
+		fake := &feedsFake{
+			feedsJSON: `[
+			  {"id": 1, "title": "Loud", "site_url": "https://loud.example", "category": {"id": 1, "title": "Flood"}},
+			  {"id": 2, "title": "Quiet", "site_url": "https://quiet.example", "category": {"id": 2, "title": "Blogs"}}
+			]`,
+			pool: map[int64][]testEntry{
+				1: fresh(makeEntries(90, 100, false, 1)),
+				2: fresh(makeEntries(3, 500, false, 2)),
+			},
+		}
+		srv := httptest.NewServer(fake.handler())
+		t.Cleanup(srv.Close)
+		t.Setenv("MINIFLUX_URL", srv.URL)
+		t.Setenv("MINIFLUX_TOKEN", "test-token")
+		return srv
+	}
+
+	labelsPath := filepath.Join(t.TempDir(), "labels.jsonl")
+	rows := []core.LabelRow{}
+	for i := 0; i < 2; i++ {
+		rows = append(rows, core.LabelRow{EntryID: int64(10 + i), URL: "u", Title: "t",
+			FeedID: 1, FeedTitle: "Loud", Label: core.LabelNeg, CapturedAt: now})
+	}
+	for i := 0; i < 10; i++ {
+		rows = append(rows, core.LabelRow{EntryID: int64(100 + i), URL: "u", Title: "t",
+			FeedID: 2, FeedTitle: "Quiet", Label: core.LabelNeg, CapturedAt: now})
+	}
+	if err := core.AppendLabels(labelsPath, rows); err != nil {
+		t.Fatalf("AppendLabels: %v", err)
+	}
+
+	run := func(cmd *FeedsCommand) string {
+		t.Helper()
+		var out bytes.Buffer
+		if err := cmd.Run(nil, &out); err != nil {
+			t.Fatalf("feeds: %v", err)
+		}
+		return out.String()
+	}
+
+	newServer(t)
+	got := run(&FeedsCommand{Days: 30, Labels: labelsPath, MinPerDay: 1.0})
+	if !strings.Contains(got, "Loud") || strings.Contains(got, "Quiet") {
+		t.Errorf("--min-per-day 1.0 should keep only Loud (3.0/day vs 0.1/day):\n%s", got)
+	}
+	if !strings.Contains(got, "showing 1 of 2") {
+		t.Errorf("filtered footer should count the shown subset:\n%s", got)
+	}
+
+	newServer(t)
+	got = run(&FeedsCommand{Days: 30, Labels: labelsPath, MinSeen: 5})
+	if strings.Contains(got, "Loud") || !strings.Contains(got, "Quiet") {
+		t.Errorf("--min-seen 5 should keep only Quiet (10 rows vs 2):\n%s", got)
+	}
+}
+
+// Without a labels file the audit still prints the volume columns (fresh
+// checkout) rather than erroring.
+func TestFeedsAuditWithoutLabels(t *testing.T) {
+	fake := &feedsFake{
+		feedsJSON: `[{"id": 1, "title": "Quiet Blog", "site_url": "https://quiet.example", "disabled": false}]`,
+		pool:      map[int64][]testEntry{1: {}},
+	}
+	srv := httptest.NewServer(fake.handler())
+	defer srv.Close()
+	t.Setenv("MINIFLUX_URL", srv.URL)
+	t.Setenv("MINIFLUX_TOKEN", "test-token")
+
+	cmd := &FeedsCommand{Days: 30, Labels: filepath.Join(t.TempDir(), "nonexistent.jsonl")}
+	var out bytes.Buffer
+	if err := cmd.Run(nil, &out); err != nil {
+		t.Fatalf("feeds without labels file: %v", err)
+	}
+	if !strings.Contains(out.String(), "Quiet Blog") {
+		t.Errorf("volume-only audit should still list the feed:\n%s", out.String())
+	}
+}
+
+// Guard: entries outside the window must not count toward volume. (Kept
+// explicit because the fake honors published_after — if the command ever
+// stops sending it, this fails loudly instead of silently inflating counts.)
+func TestFeedsAuditWindowFilter(t *testing.T) {
+	now := time.Now()
+	entries := makeEntries(3, 100, false, 1)
+	entries[0].PublishedAt = now.Add(-24 * time.Hour)       // in window
+	entries[1].PublishedAt = now.Add(-10 * 24 * time.Hour)  // in window
+	entries[2].PublishedAt = now.Add(-200 * 24 * time.Hour) // out: 200d > 30d window
+	fake := &feedsFake{
+		feedsJSON: `[{"id": 1, "title": "Sparse Blog", "site_url": "https://sparse.example", "disabled": false}]`,
+		pool:      map[int64][]testEntry{1: entries},
+	}
+	srv := httptest.NewServer(fake.handler())
+	defer srv.Close()
+	t.Setenv("MINIFLUX_URL", srv.URL)
+	t.Setenv("MINIFLUX_TOKEN", "test-token")
+
+	cmd := &FeedsCommand{Days: 30, Labels: ""}
+	var out bytes.Buffer
+	if err := cmd.Run(nil, &out); err != nil {
+		t.Fatalf("feeds: %v", err)
+	}
+	for _, line := range strings.Split(out.String(), "\n") {
+		if strings.Contains(line, "Sparse Blog") && !strings.Contains(line, " 2 ") {
+			t.Errorf("Sparse Blog volume should be 2 (window applied): %q", line)
+		}
+	}
+}