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

When neither --compact nor --no-compact is specified, issue list now
auto-detects whether compact mode should activate based on terminal
height. If the estimated non-compact table height (rows × 3 + 4 lines
overhead) exceeds process.stdout.rows, compact mode engages
automatically.

- Change --compact flag from default:false to optional:true (tri-state)
- Add shouldAutoCompact(rowCount) utility in formatters/human.ts
- Add resolveCompact() to resolve tri-state flag before rendering
- Non-TTY (piped) output always gets full (non-compact) rows
- --compact forces compact ON, --no-compact forces compact OFF

Author: BYK

src/commands/issue/list.ts

@@ -39,6 +39,7 @@ import {
 import {
   type IssueTableRow,
   muted,
+  shouldAutoCompact,
   writeIssueTable,
   writeJson,
 } from "../../lib/formatters/index.js";
@@ -84,7 +85,7 @@ type ListFlags = {
   readonly json: boolean;
   readonly cursor?: string;
   readonly fresh: boolean;
-  readonly compact: boolean;
+  readonly compact?: boolean;
 };
 
 /** @internal */ export type SortValue = "date" | "new" | "freq" | "user";
@@ -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`);
@@ -1091,7 +1107,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) {
@@ -1203,8 +1221,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,34 @@ 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: top border, header, header separator, bottom border. */
+const TABLE_LINE_OVERHEAD = 4;
+
+/**
+ * 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 +603,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 separator + bottom border. */
+const OVERHEAD = 4;
+
+/** 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 }
+    );
+  });
+});