feat(issue-list): auto-compact when table exceeds terminal height (#395)

Auto-detect compact mode based on terminal height. When the estimated
non-compact table height exceeds `process.stdout.rows`, compact
(single-line)
rows activate automatically — no flag needed.

### Changes

- **`--compact` is now tri-state**: `--compact` forces ON,
`--no-compact` forces
  OFF, omitted → auto-detect via terminal height
- **`shouldAutoCompact(rowCount)`** in `src/lib/formatters/human.ts`:
estimates
table height as `rows × 3 + 4` (2-line content + separator per row, plus
border/header overhead). Returns `false` for non-TTY to preserve full
output
  for piped/scripted usage.
- **`resolveCompact(flag, rowCount)`** in the list command resolves the
tri-state
  before passing to `writeIssueTable()`

### Behavior

| Invocation | Result |
|---|---|
| `sentry issue list` | Auto: compact if table won't fit terminal |
| `sentry issue list --compact` | Always compact |
| `sentry issue list --no-compact` | Always full 2-line rows |
| `sentry issue list \| jq` | Full output (non-TTY) |

### Tests

7 property-based tests in
`test/lib/formatters/auto-compact.property.test.ts`
covering non-TTY fallback, edge cases, monotonicity, and determinism.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: BYK

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -234,7 +234,7 @@ List issues in a project
 - `-t, --period <value> - Time period for issue activity (e.g. 24h, 14d, 90d) - (default: "90d")`
 - `-c, --cursor <value> - Pagination cursor for <org>/ or multi-target modes (use "last" to continue)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
-- `--compact - Single-line rows for compact output`
+- `--compact - Single-line rows for compact output (auto-detects if omitted)`
 - `--json - Output as JSON`
 - `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
@@ -681,7 +681,7 @@ List issues in a project
 - `-t, --period <value> - Time period for issue activity (e.g. 24h, 14d, 90d) - (default: "90d")`
 - `-c, --cursor <value> - Pagination cursor for <org>/ or multi-target modes (use "last" to continue)`
 - `-f, --fresh - Bypass cache and fetch fresh data`
-- `--compact - Single-line rows for compact output`
+- `--compact - Single-line rows for compact output (auto-detects if omitted)`
 - `--json - Output as JSON`
 - `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 

src/commands/issue/list.ts

@@ -39,6 +39,7 @@ import {
 import {
   type IssueTableRow,
   muted,
+  shouldAutoCompact,
   writeIssueTable,
   writeJsonList,
 } from "../../lib/formatters/index.js";
@@ -83,7 +84,7 @@ type ListFlags = {
   readonly json: boolean;
   readonly cursor?: string;
   readonly fresh: boolean;
-  readonly compact: boolean;
+  readonly compact?: boolean;
   readonly fields?: string[];
 };
 
@@ -100,6 +101,19 @@ const USAGE_HINT = "sentry issue list <org>/<project>";
  */
 const MAX_LIMIT = 1000;
 
+/**
+ * Resolve the effective compact mode from the flag tri-state and issue count.
+ *
+ * - `true` / `false` — explicit user override, returned as-is
+ * - `undefined` — auto-detect based on terminal height vs estimated table height
+ */
+function resolveCompact(flag: boolean | undefined, rowCount: number): boolean {
+  if (flag !== undefined) {
+    return flag;
+  }
+  return shouldAutoCompact(rowCount);
+}
+
 function parseSort(value: string): SortValue {
   if (!VALID_SORT_VALUES.includes(value as SortValue)) {
     throw new Error(
@@ -829,7 +843,9 @@ async function handleOrgAllIssues(options: OrgAllIssuesOptions): Promise<void> {
       isMultiProject: true,
     },
   }));
-  writeIssueTable(stdout, issuesWithOpts, { compact: flags.compact });
+  writeIssueTable(stdout, issuesWithOpts, {
+    compact: resolveCompact(flags.compact, issuesWithOpts.length),
+  });
 
   if (hasMore) {
     stdout.write(`\nShowing ${issues.length} issues (more available)\n`);
@@ -1092,7 +1108,9 @@ async function handleResolvedTargets(
       : `Issues from ${validResults.length} projects`;
 
   writeListHeader(stdout, title);
-  writeIssueTable(stdout, issuesWithOptions, { compact: flags.compact });
+  writeIssueTable(stdout, issuesWithOptions, {
+    compact: resolveCompact(flags.compact, issuesWithOptions.length),
+  });
 
   let footerMode: "single" | "multi" | "none" = "none";
   if (isMultiProject) {
@@ -1204,8 +1222,8 @@ export const listCommand = buildListCommand("issue", {
       fresh: FRESH_FLAG,
       compact: {
         kind: "boolean",
-        brief: "Single-line rows for compact output",
-        default: false,
+        brief: "Single-line rows for compact output (auto-detects if omitted)",
+        optional: true,
       },
     },
     aliases: {

src/lib/formatters/human.ts

@@ -393,6 +393,41 @@ function computeAliasShorthand(shortId: string, projectAlias?: string): string {
 /** Minimum terminal width to show the TREND sparkline column. */
 const TREND_MIN_TERM_WIDTH = 100;
 
+/** Lines per issue row in non-compact mode (2-line content + separator). */
+const LINES_PER_DEFAULT_ROW = 3;
+
+/**
+ * Fixed line overhead for the rendered table.
+ *
+ * Top border (1) + header row (1) + header separator (1) + bottom border (1) = 4,
+ * minus 1 because the last data row has no trailing separator (row separators
+ * are drawn between data rows only: `r > 0 && r < allRows.length - 1`).
+ * Net overhead = 3.
+ */
+const TABLE_LINE_OVERHEAD = 3;
+
+/**
+ * Determine whether auto-compact should activate based on terminal height.
+ *
+ * Returns `true` when the estimated non-compact table height exceeds the
+ * terminal's row count, meaning compact mode would keep output on-screen.
+ *
+ * Returns `false` when terminal height is unknown (non-TTY/piped output)
+ * to prefer full output for downstream parsing.
+ *
+ * @param rowCount - Number of issue rows to render
+ * @returns Whether compact mode should be used
+ */
+export function shouldAutoCompact(rowCount: number): boolean {
+  const termHeight = process.stdout.rows;
+  if (!termHeight) {
+    return false;
+  }
+  const estimatedHeight =
+    rowCount * LINES_PER_DEFAULT_ROW + TABLE_LINE_OVERHEAD;
+  return estimatedHeight > termHeight;
+}
+
 /**
  * Substatus label for the TREND column's second line.
  * Matches Sentry web UI visual indicators.
@@ -575,6 +610,9 @@ function formatTrendCell(issue: SentryIssue, compact = false): string {
  * Compact mode (`--compact`): single-line rows for quick scanning. All cells
  * collapsed to one line, long titles truncated with "…".
  *
+ * Callers should resolve auto-compact (via {@link shouldAutoCompact}) before
+ * passing `compact` — this function treats `undefined` as `false`.
+ *
  * @param stdout - Output writer
  * @param rows - Issues with formatting options
  * @param options - Display options

test/lib/formatters/auto-compact.property.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Property-Based Tests for shouldAutoCompact
+ *
+ * Verifies invariants of the terminal-height-based auto-compact heuristic.
+ * Since shouldAutoCompact reads process.stdout.rows, tests save/restore the
+ * property around each assertion.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { assert as fcAssert, integer, nat, property, tuple } from "fast-check";
+import { shouldAutoCompact } from "../../../src/lib/formatters/human.js";
+import { DEFAULT_NUM_RUNS } from "../../model-based/helpers.js";
+
+/** Lines per non-compact row (2 content + 1 separator). */
+const LINES_PER_ROW = 3;
+
+/** Fixed overhead: top border + header + header sep + bottom border − 1 (no trailing row sep). */
+const OVERHEAD = 3;
+
+/** Save original process.stdout.rows so we can restore it after each test. */
+let originalRows: number | undefined;
+
+beforeEach(() => {
+  originalRows = process.stdout.rows;
+});
+
+afterEach(() => {
+  Object.defineProperty(process.stdout, "rows", {
+    value: originalRows,
+    writable: true,
+    configurable: true,
+  });
+});
+
+/** Set process.stdout.rows for testing. */
+function setTermHeight(rows: number | undefined): void {
+  Object.defineProperty(process.stdout, "rows", {
+    value: rows,
+    writable: true,
+    configurable: true,
+  });
+}
+
+describe("property: shouldAutoCompact", () => {
+  test("returns false when terminal height is undefined (non-TTY)", () => {
+    fcAssert(
+      property(nat(500), (rowCount) => {
+        setTermHeight(undefined);
+        expect(shouldAutoCompact(rowCount)).toBe(false);
+      }),
+      { numRuns: DEFAULT_NUM_RUNS }
+    );
+  });
+
+  test("returns false when terminal height is 0", () => {
+    fcAssert(
+      property(nat(500), (rowCount) => {
+        setTermHeight(0);
+        expect(shouldAutoCompact(rowCount)).toBe(false);
+      }),
+      { numRuns: DEFAULT_NUM_RUNS }
+    );
+  });
+
+  test("zero rows only triggers compact if overhead alone exceeds terminal", () => {
+    fcAssert(
+      property(integer({ min: 1, max: 500 }), (termHeight) => {
+        setTermHeight(termHeight);
+        // With 0 rows, estimated = OVERHEAD. Compact iff OVERHEAD > termHeight.
+        expect(shouldAutoCompact(0)).toBe(OVERHEAD > termHeight);
+      }),
+      { numRuns: DEFAULT_NUM_RUNS }
+    );
+  });
+
+  test("returns true when estimated height exceeds terminal height", () => {
+    fcAssert(
+      property(
+        tuple(integer({ min: 1, max: 200 }), integer({ min: 5, max: 500 })),
+        ([rowCount, termHeight]) => {
+          const estimated = rowCount * LINES_PER_ROW + OVERHEAD;
+          if (estimated > termHeight) {
+            setTermHeight(termHeight);
+            expect(shouldAutoCompact(rowCount)).toBe(true);
+          }
+        }
+      ),
+      { numRuns: DEFAULT_NUM_RUNS }
+    );
+  });
+
+  test("returns false when estimated height fits within terminal", () => {
+    fcAssert(
+      property(
+        tuple(integer({ min: 1, max: 200 }), integer({ min: 5, max: 2000 })),
+        ([rowCount, termHeight]) => {
+          const estimated = rowCount * LINES_PER_ROW + OVERHEAD;
+          if (estimated <= termHeight) {
+            setTermHeight(termHeight);
+            expect(shouldAutoCompact(rowCount)).toBe(false);
+          }
+        }
+      ),
+      { numRuns: DEFAULT_NUM_RUNS }
+    );
+  });
+
+  test("is monotonic: more rows never decreases compactness", () => {
+    fcAssert(
+      property(
+        tuple(nat(100), nat(100), integer({ min: 10, max: 200 })),
+        ([a, b, termHeight]) => {
+          setTermHeight(termHeight);
+          const smaller = Math.min(a, b);
+          const larger = Math.max(a, b);
+          const compactSmall = shouldAutoCompact(smaller);
+          const compactLarge = shouldAutoCompact(larger);
+          // If fewer rows triggers compact, more rows must also trigger compact
+          if (compactSmall) {
+            expect(compactLarge).toBe(true);
+          }
+        }
+      ),
+      { numRuns: DEFAULT_NUM_RUNS }
+    );
+  });
+
+  test("is deterministic: same inputs produce same output", () => {
+    fcAssert(
+      property(
+        tuple(nat(200), integer({ min: 1, max: 500 })),
+        ([rowCount, termHeight]) => {
+          setTermHeight(termHeight);
+          const result1 = shouldAutoCompact(rowCount);
+          const result2 = shouldAutoCompact(rowCount);
+          expect(result1).toBe(result2);
+        }
+      ),
+      { numRuns: DEFAULT_NUM_RUNS }
+    );
+  });
+});