docs(comments): rewrite comments across all crates to the guidelines

Sweep every first-party crate source (1956 .rs files) to the project comment guidelines: delete redundant restatements, decorative banners, change narration, and end-of-line comments; keep and tighten the crucial ones (invariants, bug rationale, SAFETY blocks, ported-source attribution). No functional code changed. Every edit is proven comment-only against the prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a separate doctest-fence check. Where removing a comment made rustfmt or clippy want to re-lay-out adjacent code, the minimal triggering comment is restored so code tokens stay byte-identical. Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy --workspace --all-targets (0 warnings). Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for these guidelines (flags banners, end-of-line comments, change narration, and commented-out code).
2026-07-23 16:55:39 -04:00
parent ff0fb56c67
commit a02b555e66
1458 changed files with 10729 additions and 21750 deletions
@@ -14,10 +14,9 @@ use crate::common::*;
 #[ignore]
 async fn minimal_commits_response_to_scrollback() {
    let content = ContentController::start().await.expect("start content");
-    // Sentinel on the FIRST rendered row; 80 code-block rows >> the 50-row
-    // screen, so the head scrolls into native scrollback once the block commits.
-    // (Prose lines would markdown-reflow into one short paragraph that fits on
-    // screen — see `tall_response`.)
+    // 80 code-block rows overflow the 50-row screen, pushing the sentinel line
+    // into scrollback. (Prose would markdown-reflow to fit on screen instead —
+    // see `tall_response`.)
    content.set_response(tall_response(MOCK_RESPONSE_SENTINEL, 80));

    let mut harness = spawn_minimal(&content);
@@ -12,9 +12,9 @@ use crate::common::*;
 #[ignore]
 async fn minimal_committed_content_survives_overlay_grow() {
    let content = ContentController::start().await.expect("start content");
-    // Sentinel on the first rendered row; 80 code-block rows overflow the screen
-    // so the head reaches native scrollback (prose would reflow to fit on screen
-    // and never scroll — see `tall_response`).
+    // 80 code-block rows overflow the screen, pushing the sentinel line into
+    // scrollback (prose would reflow to fit on screen and never scroll —
+    // see `tall_response`).
    content.set_response(tall_response(MOCK_RESPONSE_SENTINEL, 80));

    let mut harness = spawn_minimal(&content);
@@ -28,8 +28,6 @@ async fn minimal_continue_reprints_transcript() {
        .expect("turn 1 committed to scrollback");
    quit_minimal(&mut first);

-    // Resume the same session. The transcript is reprinted into native
-    // scrollback (no separate history pane in minimal).
    let mut resumed = spawn_minimal_in_dir(
        &content,
        DEFAULT_ROWS,
@@ -46,7 +44,6 @@ async fn minimal_continue_reprints_transcript() {
            )
        });

-    // A follow-up turn still works in the resumed session.
    content.set_response(format!("{} resumed payload.", turn_sentinel(2)));
    resumed
        .inject_keys(b"again\r")
@@ -14,7 +14,7 @@ async fn minimal_ctrl_c_arms_and_quits() {
    let mut harness = spawn_minimal(&content);
    wait_minimal_ready(&mut harness);

-    // First Ctrl+C (CSI legacy ETX). Arms quit + shows the hint under the prompt.
+    // \x03 is the legacy ETX byte for Ctrl+C.
    harness.inject_keys(b"\x03").expect("inject Ctrl+C");
    harness
        .wait_for_text("again to quit", Duration::from_secs(5))
@@ -25,7 +25,6 @@ async fn minimal_ctrl_c_arms_and_quits() {
            )
        });

-    // Second Ctrl+C within the confirm window exits the process.
    harness.inject_keys(b"\x03").expect("inject Ctrl+C again");
    let code = harness.wait_exit_code(Duration::from_secs(5));
    assert!(
@@ -48,11 +48,8 @@ async fn minimal_ctrl_o_send_now_queued_apple_terminal() {
        .wait_for_text("1 queued", Duration::from_secs(10))
        .expect("queue indicator");

-    // Empty composer + queue: Ctrl+O must yield to send-now, not transcript.
-    // Cancel-and-send: the shell silently cancels turn 1 (its held completion
-    // is irrelevant — the abort wins) and the row commits as a standard "❯ "
-    // prompt block for its own turn. Turn 1 is still gated open here, so the
-    // queued row cannot have promoted FIFO.
+    // Turn 1 is still gated open here, so the queued row cannot have
+    // promoted FIFO — this exercises the cancel-and-send path specifically.
    harness.inject_keys(CTRL_O).expect("Ctrl+O send-now");
    // Generous deadline: with turn 1 gated open there is no promotion race
    // left to mask — this wait is pure render latency, which under heavy
@@ -60,9 +60,8 @@ async fn minimal_double_esc_committed_queued_prompt_single_render() {
        harness.full_text()
    );

-    // Cancel the promoted turn pre-first-token. The committed block forces
-    // the standard cancel path (rewind skipped): marker renders, composer
-    // stays empty, and the prompt count does NOT grow.
+    // Cancel pre-first-token, while the committed block is still the only
+    // copy on screen.
    harness.inject_keys(keys::CTRL_C).expect("Ctrl+C cancel");
    harness
        .wait_for_full_text("Turn cancelled by user", Duration::from_secs(15))
@@ -4,9 +4,9 @@ use crate::common::*;

 /// Minimal mode paints the welcome card edge-to-edge (no outer horizontal pad).
 /// The live region's status / prompt / info rows and committed user+agent blocks
-/// must share that left edge — previously they sat at `block_pad_left + accent`
-/// (= 3 columns of blank gutter), which looked misaligned against the welcome
-/// box. Assert every non-blank visible row either is welcome-card chrome
+/// must share that left edge — a `block_pad_left + accent` offset (3 columns
+/// of blank gutter) reads as misaligned against the welcome box. Assert every
+/// non-blank visible row either is welcome-card chrome
 /// (border / logo interior) or starts at column 0.
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 #[ignore]
@@ -56,8 +56,8 @@ async fn minimal_flush_left_no_hpad() {
    );

    // Slash menu: typing a command prefix opens the dropdown below the prompt.
-    // Its rows must be flush-left too — previously the panel sat at the layout
-    // hpad and the item rows one further column in (`❯ /transcript` at col 3).
+    // Its rows must be flush-left too — a panel at the layout hpad with item
+    // rows one further column in (`❯ /transcript` at col 3) is misaligned.
    harness
        .inject_keys(b"/tra")
        .expect("type slash command prefix");
@@ -78,7 +78,7 @@ async fn minimal_flush_left_no_hpad() {

    // Permission modal: a scripted `run_terminal_command` tool call (no --yolo)
    // opens the prompt-replacing permission modal. Its rows must be flush-left
-    // too — previously the whole modal sat at the layout hpad (2 columns in).
+    // too — the modal must not sit at the layout hpad (2 columns in).
    // The accent `┃` paints the modal's first column, so a correct row has zero
    // leading spaces.
    content.set_response("PERMISSION_SETTLED — turn finished after the allow.");
@@ -133,8 +133,8 @@ async fn minimal_flush_left_no_hpad() {

 /// For each `needle`, find the first screen line containing it and assert that
 /// line has no leading ASCII spaces (flush-left). Welcome-card rows start with
-/// box-drawing chars at col 0 already; this targets the previously-padded
-/// live/committed content.
+/// box-drawing chars at col 0 already; this targets live/committed content
+/// that must not carry a leading pad.
 fn assert_flush_left_live_rows(screen: &str, needles: &[&str], phase: &str) {
    for needle in needles {
        let line = screen
@@ -43,7 +43,6 @@ async fn minimal_new_session_keeps_history_and_resets() {
        harness.scrollback_text()
    );

-    // `/new` → fresh session: commits a second welcome card and resets the frontier.
    inject_keys_paced(&mut harness, b"/new");
    harness.inject_keys(b"\r").expect("submit /new");

@@ -59,14 +58,12 @@ async fn minimal_new_session_keeps_history_and_resets() {
        harness.full_text()
    );

-    // Prior turn's committed lines remain in native scrollback (not wiped).
    assert!(
        harness.contains_full_text(&turn_sentinel(1)),
        "prior turn must remain in native scrollback after /new\nfull:\n{}",
        harness.full_text()
    );

-    // A fresh turn streams in the new session.
    content.set_response(format!("{} new session payload.", turn_sentinel(2)));
    harness
        .inject_keys(b"hi\r")
@@ -51,7 +51,6 @@ async fn minimal_queue_indicator_shows_while_running() {
        .wait_for_full_text("#1  second queued prompt", Duration::from_secs(10))
        .expect("the snapshot lists the queued text");

-    // The queued prompt eventually promotes and runs as turn 2.
    harness
        .wait_for_full_text("STEPTWO", Duration::from_secs(40))
        .expect("queued prompt promoted and ran");
@@ -24,7 +24,6 @@ async fn minimal_resize_preserves_committed_scrollback() {
        .inject_keys(format!("{PROMPT}\r").as_bytes())
        .expect("submit prompt");

-    // Precondition: the committed head must be in native scrollback first.
    let deadline = Instant::now() + Duration::from_secs(40);
    while Instant::now() < deadline && !harness.scrollback_text().contains(MOCK_RESPONSE_SENTINEL) {
        harness.update(Duration::from_millis(100));
@@ -56,7 +55,6 @@ async fn minimal_resize_preserves_committed_scrollback() {
        harness.full_text()
    );

-    // The prompt is still functional: a second turn streams after the resize.
    content.set_response(format!("{} after resize.", turn_sentinel(2)));
    harness
        .inject_keys(b"again\r")
@@ -23,7 +23,6 @@ async fn minimal_settings_modal_opens_and_closes() {
        .wait_for_text("Appearance", Duration::from_secs(10))
        .expect("settings editor renders inline");

-    // Esc closes it; the idle prompt status returns and the editor is gone.
    harness.inject_keys(keys::ESC).expect("close settings");
    harness
        .wait_for_text(MINIMAL_IDLE_SENTINEL, Duration::from_secs(10))
@@ -40,26 +40,22 @@ async fn minimal_short_response_stays_on_screen() {

    let rows = DEFAULT_ROWS;

-    // 1) The short response is on the visible screen …
    assert!(
        harness.screen_contents().contains(MOCK_RESPONSE_SENTINEL),
        "short response must stay on the visible screen\nscreen:\n{}",
        harness.screen_contents()
    );
-    // 2) … and was NOT force-pushed into native scrollback. Content-anchored: a
-    //    response that fits stays put; only content taller than the screen scrolls
-    //    (proven separately by `minimal_commits_response_to_scrollback`).
+    // Content-anchored: a response that fits stays put; only content taller than
+    // the screen scrolls (proven separately by `minimal_commits_response_to_scrollback`).
    assert!(
        !harness.scrollback_text().contains(MOCK_RESPONSE_SENTINEL),
        "short response must not be pushed into scrollback\nscrollback:\n{}",
        harness.scrollback_text()
    );

-    // 3) The prompt sits directly after the (short) conversation, HIGH on the
-    //    screen, with the rest of the window left blank below it — NOT pinned to
-    //    the bottom with a big gap above (the regression). The cursor is always
-    //    on the focused prompt, so its row is the robust signal: bottom-pin puts
-    //    it near `rows - 1`; content-anchored keeps it in the upper portion.
+    // The cursor is always on the focused prompt, so its row is the robust
+    // signal: bottom-pin would put it near `rows - 1`; content-anchored keeps
+    // it in the upper portion, directly after the short conversation.
    let (cursor_row, _cursor_col) = harness.cursor_position();
    assert!(
        cursor_row < rows - 12,
@@ -68,10 +64,8 @@ async fn minimal_short_response_stays_on_screen() {
        harness.screen_contents()
    );

-    // 4) Nothing is rendered near the bottom of the screen: the last non-blank
-    //    row (the prompt's info bar) is well above the last row. Found explicitly
-    //    (not via trailing padding) so the check is independent of how the
-    //    emulator represents empty rows.
+    // Find the last non-blank row explicitly (not via trailing padding) so the
+    // check is independent of how the emulator represents empty rows.
    let screen = harness.screen_contents();
    let last_non_blank = screen
        .lines()
@@ -97,7 +97,6 @@ async fn minimal_transcript_expands_collapsed_thinking() {
            )
        });

-    // And the inline TUI survives the suspend/restore round trip.
    harness
        .wait_for_text(MINIMAL_IDLE_SENTINEL, Duration::from_secs(10))
        .expect("inline TUI restored after the pager exited");
@@ -56,8 +56,6 @@ async fn minimal_transcript_opens_in_pager() {
        harness.full_text()
    );

-    // The pager process survives the suspend/restore round-trip and returns to
-    // the idle prompt.
    harness
        .wait_for_text(MINIMAL_IDLE_SENTINEL, Duration::from_secs(10))
        .expect("inline TUI restored after the pager exited");