Skip to content

refactor(webview): Compact the webview, script and test comments #750

Closed

Description

@omesser

Part 6 of #744. The broadest slice by file count, the smallest by volume.

Scope

58 files, 7,709 code lines, 2,032 comment lines (21%), 155 blocks over 3 lines, 89 citing an issue or ADR.

  • src/*.js — the webview. chat.js (194), main.js (177) are the heaviest, and src/main.js is 38% comments.
  • scripts/ — verify-overlay.sh (170), import-pet.py (137).
  • tests/ — 325 lines across 22 files.

Land it as one PR

No single file exceeds 200 comment lines, so this stays reviewable whole.

Watch out, three things

  1. tests/chat-ui-tokens.test.js:60 strips CSS comments with a single-line regex (/\/\*[^*]*\*\//g). A multi-line CSS comment containing a hex color false-positives the hard-coded-color check. If you reflow a CSS comment across lines and it mentions a color, you will turn CI red in a way that looks like a design violation.

  2. scripts/import-pet.py:1179 asserts that generated character.toml keeps art notes in TOML comments (assert "# Mapping:" in manifest). Paired with scripts/make-character-gallery.py:106. This is the one place in the repo where comment placement is load-bearing. Do not touch those comments or the code that writes them.

  3. Verify and test scripts get no phase-narrating comments. // Phase 1: add cards is exactly what this effort removes — the assertion or log string already documents the step, as in assert(ok, 'persisted across restart').

tests/ comments are mostly explaining what a test asserts. If the test name and the assertion already say it, the comment is a restatement and goes.

Before you start

Read #744 in full. It carries the bar, the five-step decision procedure, the hazards and the verification checklist. This issue only names your slice. Wait for #745 (the amended standard) so you compact to the new bar, not the old one.

The rule, in one line

Cap blocks at 3 lines. Delete blocks that only restate the code. Keep the one-line summary on any public item. A comment you do not understand is not a comment you are qualified to delete.

Truncating alone lands at 13.4%, not 10%. Two rules, not one.

Verify

  • The diff touches no code line. Prove it over git diff -U0, do not assert it.
  • cargo test --workspace and node --test tests/*.test.js green, same counts before and after.
  • cargo clippy --workspace --all-targets -- -D warnings green.
  • Add the windows label to each PR, or that leg is lint-only and will not run the tests.
  • Census before and after in each PR description.

— Claude Code agent, on @omesser's behalf.

Activity

  1. added
    ready-for-agentFully specified, ready for an AFK agent
    p2Eventually: real, but nothing waits on it
    on Sep 15, 2026
  2. added this to the V1 milestone on Sep 15, 2026
  3. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    Correction: the CSS hazard here is a silent disarm, not a false positive

    The issue body above describes tests/chat-ui-tokens.test.js as risking a false positive on a multi-line comment containing a hex color. That is real but minor. The serious one is the opposite, and it stays green.

    tests/chat-ui-tokens.test.js:30-32 decides where a .chat-ui-* design block starts by counting braces per raw line, comments included:

    const opens = (line.match(/{/g) ?? []).length;
    if (!skipping && depth === 0 && line.includes(".chat-ui-") && opens > 0) {
      skipping = true;
    }

    src/chat-ui.css:6 and :7 are comment lines that already contain .chat-ui-*:

     * a :root block naming the tokens, one .chat-ui-* block setting them, and the
     * rules that consume them. A second design is a second .chat-ui-* block and
    

    They carry no brace today, so opens > 0 is false and the guard holds. Rewrap either line so a { lands on it and skipping turns on at depth 0 and never turns off — the ADR-0013 hard-coded-colour lint silently stops checking the rest of the stylesheet, and the test still passes.

    A false positive turns CI red and you fix it. This turns a lint off and nobody notices.

    So for this part specifically: run node --test tests/*.test.js before and after and diff the pass list, not just the exit code. Better, reflow no comment in src/chat-ui.css that mentions .chat-ui-; there are only two and neither is long.

    Same shape elsewhere in your scope: tests/bubble.test.js:461 regexes src/main.js and src-tauri/src/main.rs; tests/connect-buttons.test.js:24 slices harness.rs between source literals.

    — Claude Code agent, on @omesser's behalf.

  4. self-assigned this
    on Sep 16, 2026
  5. moved this from 👷 Todo to 🏗 In Progress in Fidgeton Sep 16, 2026
  6. moved this from 🏗 In Progress to 🏁 Done in Fidgeton Sep 16, 2026
  7. omesser commented on Sep 16, 2026

    @omesser
    OwnerAuthor

    Shipped on main via #765

    PR #765 merged (8976c1ad). Child 6 of #744 is done.

    On main now: comment-only compaction across the 71 touched files under src/, scripts/, and tests/ (vendor/fixtures excluded). Census in the PR: comment lines 2,845 → 1,906 (13.9% after restoring verify/bench one-line step labels), blocks over 3 lines 218 → 38. Code lines unchanged; node and cargo suites green with identical named pass lists vs main; the three #750 hazards (CSS hex / import-pet TOML comment asserts / phase narration) were handled as specified.

    Acceptance met. This issue was auto-closed by the merge; leaving it closed as completed.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

p2Eventually: real, but nothing waits on itready-for-agentFully specified, ready for an AFK agentrefactoring

Projects

  • Status
    Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions