Skip to content

refactor(core): Compact the Engine's comments, remaining files (#747 slice 3) - #780

Merged
omesser merged 1 commit into
mainfrom
refactor/747-core-comments
Sep 16, 2026
Merged

omesser merged 1 commit into
mainfrom
refactor/747-core-comments

Conversation

@omesser

@omesser omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner

Slice 3 of #747 (part 3 of #744): the remaining files under crates/core/src/, every block judged against #744's five-step procedure by hand, one exact-match swap per block. No regex pass, no codemod.

What changed

12 files. Comment lines 1460 -> 898, blocks over three lines 133 -> 8. Every retained block carries a reason, a constraint, a bound or a rejected alternative; blocks that restated the code are gone, and history moved to git log.

File Code Comments before after >3ln before after Ratio before after
director/prompt.rs 115 41 23 2 1 26.3% 16.7%
engine/geometry.rs 212 145 78 12 1 40.6% 26.9%
engine/transition.rs 35 27 22 1 0 43.5% 38.6%
input.rs 484 198 130 16 0 29.0% 21.2%
lib.rs 14 5 3 1 0 26.3% 17.6%
memory.rs 568 174 114 21 4 23.5% 16.7%
overlay.rs 457 183 88 17 0 28.6% 16.1%
sensing.rs 222 64 47 7 0 22.4% 17.5%
snapshot.rs 705 165 109 15 1 19.0% 13.4%
tools.rs 392 73 49 4 0 15.7% 11.1%
visibility.rs 488 192 128 16 1 28.2% 20.8%
window_source.rs 351 193 107 21 0 35.5% 23.4%
Total 4043 1460 898 133 8 26.5% 18.2%

Eight blocks stay over the ceiling, each under a named #744 exception:

  • memory.rs module doc, data_dir, MemoryManifest::writing, backup_path: the four ponytail: markers, left whole. git diff -U0 origin/main -- crates/core/src/memory.rs | grep -i ponytail is empty.
  • director/prompt.rs character_prompt (7 lines): blank keeping the Instance Prompt and the empty seats is a rejected alternative a reader would re-attempt.
  • engine/geometry.rs is_perch (7): first-match-in-z-order is the rejected alternative that drops the sprite through a visible edge.
  • snapshot.rs perch_eligible (7): layer == 0 is a bound that looks arbitrary; the layer numbers are what make it defensible.
  • visibility.rs module doc (8): Do Not Disturb and screen share are two rules a reader would add back.

Long function docs that explained several rules at once (dock_side_reached, footing, fullscreen_frontmost, bubble_owner, in_overlay, hit) became a 3-line summary plus a 2-3 line inline comment on the line each rule governs. Every bare issue reference in these files (#6 #39 #78 #85 #98 #100 #109 #128 #145 #156 #176 #177 #178 #188 #247 #277 #288 #362 #395 #443 #502 #657) is dropped with its fact kept; ADR and DESIGN.md citations stay. One codespell hit (unparseable) fixed in prose.

Skipped, and why

Stale cross-reference in #747: it says to wait for #745 (the amended standard). #745's own body resequences it to land last, after #747-#750, because it quotes source verbatim. This PR compacts to the bar in #744 and #747's one-line rule; do not stall on #745.

How to verify

No code line changes. Over git diff -U0, printing every added or removed line that is not wholly a comment or blank, then the count:

#!/bin/sh
# Prints every added/removed diff line that is not wholly a comment or blank.
# Empty output = the diff touches no code line. Usage: no-code-lines.sh <base>
git diff -U0 "$1" -- 'crates/core/src/*.rs' | grep -E '^[+-]' | grep -vE '^(\+\+\+|---)' \
  | sed -E 's/^[+-][[:space:]]*//' | grep -vE '^(//|$)'
echo "non-comment changed lines: $(git diff -U0 "$1" -- 'crates/core/src/*.rs' | grep -E '^[+-]' | grep -vE '^(\+\+\+|---)' | sed -E 's/^[+-][[:space:]]*//' | grep -cvE '^(//|$)')"

Output on this branch against origin/main:

non-comment changed lines: 0

tools.rs kept one restating comment (// No instance_id provided) because deleting it makes rustfmt collapse the surrounding None => { match .. } block, which would be a code-line change.

Tests, diffed by name. cargo test --workspace: 1015 passed, 4 ignored before and after; the 1019 test ... ok/ignored lines sorted are byte-identical (diff empty). node --test tests/*.test.js: 212/212 before and after, names identical.

cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --all -- --check clean. Pre-commit (codespell, cargo-fmt, cargo-clippy) passed on commit.

Census from a throwaway counter: a comment line is a line that is wholly //, /// or //!; ratio is comments / (comments + code); a block is a run of consecutive comment lines.

#!/usr/bin/env python3
"""Comment census for Rust files. A comment line is a line that is wholly a
comment (//, ///, //!). Ratio is comments / (comments + code). Blank lines
are neither. Blocks are runs of consecutive comment lines."""
import sys, re
tot_code = tot_com = tot_over = 0
rows = []
for path in sys.argv[1:]:
    code = com = over = run = 0
    for line in open(path, encoding="utf-8"):
        s = line.strip()
        if not s:
            continue
        if s.startswith("//"):
            com += 1; run += 1
        else:
            code += 1
            if run > 3: over += 1
            run = 0
    if run > 3: over += 1
    rows.append((path, code, com, over))
    tot_code += code; tot_com += com; tot_over += over
for p, c, m, o in rows:
    print(f"{p:45} code {c:5} comments {m:4} >3ln {o:3} ratio {100*m/(c+m):5.1f}%")
print(f"{'TOTAL':45} code {tot_code:5} comments {tot_com:4} >3ln {tot_over:3} ratio {100*tot_com/(tot_code+tot_com):5.1f}%")

🤖 Generated with Claude Code

Slice 3 of #747: the 12 crates/core files outside engine.rs, director.rs,
character.rs and the five #689 touches. Comment lines 1460 -> 898, blocks
over three lines 133 -> 8, all eight named exceptions. No code line changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@omesser omesser added the windows Run the Windows compile job on this pull request label Sep 16, 2026
@omesser

omesser commented Sep 16, 2026

Copy link
Copy Markdown
Owner Author

CLEARED @ 6d7713d

Standards + Spec (#747 slice 3 / #744 bar).

Proven

  • No code-line changes vs PR base and vs current origin/main (git diff -U0 non-comment count = 0 on both).
  • Eight blocks over 3 lines, all named Comments are 20% of the tree: compact them to a stated bar #744 exceptions (character_prompt, is_perch, four ponytail: memory docs, perch_eligible, visibility module doc). Matches the PR table.
  • ponytail: intact — four markers present; diff does not alter their text.
  • Decision procedure spot-check on five high-risk deletions (overlay hit/mirrored, dock_side_reached, bubble_owner, usable_frame, press_target): why/constraint kept in shorter form, not dropped.
  • windows label present (required so the Windows leg runs tests).
  • CI green. Mergeable clean.

Soft

Merge when you want. I will not merge without your yes.

— Cursor agent (Architect), on @omesser's behalf.

@omesser
omesser merged commit 1363cf6 into main Sep 16, 2026
8 checks passed
@omesser
omesser deleted the refactor/747-core-comments branch September 17, 2026 11:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

windows Run the Windows compile job on this pull request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant