feat(metrics): add client-side list filters (FT-1966)

[joalves]

Summary

abs metrics list can return hundreds of metrics with no way to narrow them. This adds client-side filtering flags so users can filter by metric type, goal, outlier-limiting, goal property filter, impact direction, and CUPED.

When any of these filters is active, the CLI fetches all pages, filters locally, and prints a N results (filtered). footer instead of the page-based one. When none are active, behavior is unchanged (single page). All filtering is client-side — server-side equivalents are a documented follow-up.

New flags:

• --metric-type <values> — by type (comma-separated, OR)
• --goal <values> — by goal name or ID; matches numerator and denominator goals
• --outlier-limiting / --no-outlier-limiting and --outlier-method <values>
• --has-property-filter / --no-property-filter, --property-filter-path <values>, --property-filter-contains <text>
• --impact-direction <values> (positive/negative/unknown)
• --cuped / --no-cuped

Filters combine with AND across flags, OR within a comma-separated list.

Architecture:

• src/core/metrics/filter.ts — pure parse/validate/filter module
• src/core/metrics/list.ts — listAllMetrics pages through every metric (resolving owners/teams once)
• src/lib/utils/list-command.ts + pagination.ts — optional isClientFiltered hook + printFilteredFooter
• src/commands/metrics/index.ts — wiring

JIRA: FT-1966

Test Plan

• Unit tests for parse/validate and every filter predicate (numerator + denominator, tri-state booleans, property-filter string/object/empty-wrapper/var.path)
• listAllMetrics pagination tests (multi-page, single-page, resolve-once)
• Command-level tests for each flag path + validation rejection + --has/--no-property-filter conflict
• Full suite green (2505 passed, 0 failed), typecheck + lint + prettier clean
• Live smoke test against latam profile: filtering narrows 200+ metrics to filtered subsets with the (filtered) footer; -o json emits filtered JSON

Summary by CodeRabbit

• New Features

  • Client-side filtering for the metrics list command, applying filters across all pages
  • New filter options: metric type, goal, CUPED toggle, property-filter controls, impact direction and outlier-related flags
  • List command now reports filtered totals in the footer when client filtering is active

• Documentation

  • Added guidance and examples for client-side metric list filters and flag behaviours

• Tests

  • Expanded test coverage for filtering logic, pagination and footer behaviour

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 75e2ccab-2ddb-40d8-9c8e-45f8a68250e6

📥 Commits

Reviewing files that changed from the base of the PR and between bc785d0 and 247c07b.

📒 Files selected for processing (2)

• src/core/metrics/list.ts
• src/core/metrics/metrics.test.ts

---

Walkthrough

This PR adds client-side filtering to abs metrics list. It introduces a filtering module that parses/validates CLI filter flags and composes predicates for type, goal, outlier settings, CUPED, and property filters. A new listAllMetrics fetches metrics across pages. The list-command framework gains an isClientFiltered hook and a filtered-results footer. The metrics command parses/validates filter options, fetches all metrics when filters are active, applies client-side filtering, and exposes new CLI flags. Tests and README documentation were added.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Filters hop across each row and line,
I gather every metric, every sign.
Type, goal, CUPED — I sniff and sort,
Pages undone, the list is short.
A rabbit’s tweak — now results align!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 3.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately summarizes the main change: adding client-side filtering capabilities to the metrics list command, which is the primary focus across all modified files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/FT-1966/metrics-list-filters

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

src/core/metrics/list.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

src/core/metrics/metrics.test.ts

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/metrics/list.ts`:
- Around line 66-87: The loop in listAllMetrics stops at FETCH_ALL_MAX_PAGES and
always returns pagination.hasMore: false, which can silently truncate results;
fix by tracking whether we hit the page cap or whether the last fetched page was
full and use that to set hasMore. Concretely, inside listAllMetrics (the for
loop that calls client.listMetrics) capture the length of the last fetched page
into a variable (e.g., lastFetchedLength), and set a boolean hitCap when page
=== FETCH_ALL_MAX_PAGES and lastFetchedLength === pageSize; after the loop
return pagination.hasMore = hitCap || lastFetchedLength === pageSize so callers
see there may be more pages when the cap was reached or the final page was full.
Ensure you reference client.listMetrics, FETCH_ALL_MAX_PAGES, pageSize and
listAllMetrics when making the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 955c3d04-9248-4801-b2a5-412e81c793ac

📥 Commits

Reviewing files that changed from the base of the PR and between b211c63 and bc785d0.

📒 Files selected for processing (10)

• README.md
• src/commands/metrics/index.ts
• src/commands/metrics/metrics.test.ts
• src/core/metrics/filter.test.ts
• src/core/metrics/filter.ts
• src/core/metrics/list.ts
• src/core/metrics/metrics.test.ts
• src/lib/utils/list-command.test.ts
• src/lib/utils/list-command.ts
• src/lib/utils/pagination.ts