Merge branch 'main' into docs/field-test-reports

Author: ZviBaratz

CLAUDE.md

@@ -56,7 +56,7 @@ bash skills/ego-lint/scripts/ego-lint.sh tests/fixtures/<fixture-name>
 - `apply-patterns.py` — Tier 1 pattern engine (inline YAML parser, no PyYAML dependency). Supports `guard-pattern` + `guard-window` (sliding `deque` lookback) + `guard-window-forward` (forward peeking), `replacement-pattern`, `exclude-dirs`, version-gating, `fix-min-version` (suppresses fix text when extension min shell-version is below threshold), `skip-comments` (skips matches inside `//` and `/* */` comments)
 - `check-quality.py` — Tier 2 heuristic AI slop detection (try-catch density, impossible states, pendulum patterns, empty catches, _destroyed density, mock detection, constructor resources, run_dispose comment, clipboard disclosure, network disclosure, excessive null checks, repeated getSettings, obfuscated names, mixed indentation, excessive logging, code provenance)
 - `check-metadata.py` — JSON validity, required fields, UUID format/match, shell-version (with VALID_GNOME_VERSIONS allowlist), session-modes, settings-schema, version-name, donations, gettext-domain consistency
-- `check-init.py` — Init-time Shell modification, GObject constructor detection (extension.js only; all GI namespaces, GObject.registerClass exempt, GLib value types exempt), Gio._promisify placement
+- `check-init.py` — Init-time Shell modification (module-scope + extension.js constructors only; arrow function definitions exempt), GObject constructor detection (extension.js only; all GI namespaces, GObject.registerClass exempt, GLib value types exempt), Gio._promisify placement
 - `check-lifecycle.py` — enable/disable symmetry, signal cleanup (connectSmart/SignalTracker-aware), timeout removal verification, InjectionManager, lock screen signals, selective disable detection, unlock-dialog comment, clipboard+keybinding cross-ref, prototype override detection, pkexec target validation, Soup.Session abort, D-Bus export/unexport, bus name own/unown lifecycle, timeout reassignment, subprocess cancellation, clipboard+network cross-ref, widget lifecycle, settings cleanup
 - `check-prefs.py` — Preferences file validation (ExtensionPreferences base class, GTK4/Adwaita patterns, memory leak detection, supports `src/` layout)
 - `check-gobject.py` — GObject.registerClass patterns and GTypeName validation

rules/patterns.yaml

@@ -1057,6 +1057,8 @@
   category: version-compat
   fix: "Call window.set_maximize_flags(flags) then window.maximize()"
   min-version: 49
+  guard-pattern: "get_maximized\\s*\\?"
+  guard-window: 1
 
 - id: R-VER49-09
   pattern: "\\bAppMenuButton\\b"
@@ -1084,6 +1086,8 @@
   category: version-compat
   min-version: 49
   fix: "Call unmaximize() without the MaximizeFlags parameter"
+  guard-pattern: "get_maximized\\s*\\?"
+  guard-window: 1
 
 # --- GNOME 50 migration (version-gated) ---
 # GNOME 50 removed X11 support and associated APIs.

skills/ego-lint/references/rules-reference.md

@@ -1130,10 +1130,10 @@ Rules for extension lifecycle management: enable/disable hooks, signal cleanup,
 ### R-LIFE-01: Signal Balance
 - **Severity**: advisory
 - **Checked by**: check-lifecycle.py
-- **Rule**: Detects imbalance between manual `.connect()` and `.disconnect()` calls (threshold: >2 imbalance). Recognizes `connectObject()`, `connectSmart()`, and `SignalTracker`/`SignalManager` as auto-cleanup patterns.
+- **Rule**: Detects imbalance between manual `.connect()` and `.disconnect()` calls (threshold: >2 imbalance). Recognizes `connectObject()`, `connectSmart()`, and `SignalTracker`/`SignalManager` as auto-cleanup patterns. Excludes: non-signal `.connect()` calls (no string-literal first argument), `'destroy'` signal connections (inherently self-cleaning), and signals on local/ephemeral variables (no `this` reference — garbage collected with scope).
 - **Rationale**: Unmatched signal connections are the #1 cause of extension rejections. Leaked signals cause memory leaks and crash loops.
 - **Fix**: For each `.connect()` call, ensure a matching `.disconnect()` in disable/destroy. Consider using `connectObject()` or a custom signal tracker for automatic cleanup.
-- **Tested by**: `tests/fixtures/lifecycle-basic@test/`, `tests/fixtures/signal-smart-connect@test/`
+- **Tested by**: `tests/fixtures/lifecycle-basic@test/`, `tests/fixtures/signal-smart-connect@test/`, `tests/fixtures/signal-non-gobject@test/`, `tests/fixtures/signal-destroy-connect@test/`, `tests/fixtures/signal-local-variable@test/`
 
 #### Example
 
@@ -2230,7 +2230,8 @@ Rules for APIs removed or changed in specific GNOME Shell versions. These rules
 - **Rule**: `maximize()` lost the `MaximizeFlags` parameter in GNOME 49.
 - **Rationale**: Passing `MaximizeFlags` to `maximize()` will throw in GNOME 49.
 - **Fix**: Call `window.set_maximize_flags(flags)` first, then `window.maximize()`.
-- **Tested by**: `tests/fixtures/gnome49-maximize@test/`
+- **Guard**: Suppressed when `get_maximized ?` appears on the same line (ternary version-compat pattern).
+- **Tested by**: `tests/fixtures/gnome49-compat@test/`
 
 ### R-VER49-09: AppMenuButton removal
 - **Severity**: blocking
@@ -2556,6 +2557,7 @@ Rules for APIs removed or changed in specific GNOME Shell versions. These rules
 - **Rule**: `MaximizeFlags` parameter was removed from `unmaximize()` in GNOME 49.
 - **Rationale**: The `unmaximize()` method no longer accepts a flags parameter.
 - **Fix**: Call `unmaximize()` without the `MaximizeFlags` parameter.
+- **Guard**: Suppressed when `get_maximized ?` appears on the same line (ternary version-compat pattern).
 
 ---
 

skills/ego-lint/scripts/check-init.py

@@ -61,6 +61,15 @@ def is_skip_line(line):
     return False
 
 
+# Arrow function definitions: the body after => is lazy (not executed at
+# module scope).  Detect `const fn = (...) => expr` patterns.
+ARROW_FN_DEF = re.compile(
+    r'(?:const|let|var)\s+\w+\s*=\s*'   # variable assignment
+    r'(?:\([^)]*\)|\w+)'                 # parameter list or single param
+    r'\s*=>'                              # arrow
+)
+
+
 # Shell globals that should only be accessed inside enable()/disable()
 SHELL_GLOBALS = re.compile(
     r'\bMain\.(panel|overview|layoutManager|sessionMode|messageTray|wm|'
@@ -183,6 +192,10 @@ def check_init_modifications(ext_dir):
             if is_skip_line(line):
                 continue
             if SHELL_GLOBALS.search(line):
+                # Arrow function definitions are lazy — the body after =>
+                # is not executed at module scope
+                if ARROW_FN_DEF.search(line):
+                    continue
                 violations.append(f"{rel}:{lineno}")
             elif GOBJECT_CONSTRUCTORS.search(line):
                 # GObject.registerClass() returns a class, not an instance
@@ -191,17 +204,18 @@ def check_init_modifications(ext_dir):
                     violations.append(f"{rel}:{lineno}")
 
         # Check constructor() lines
-        # GObject constructors in helper file constructors are runtime-only
-        # (only run when instantiated from enable()), so only flag in extension.js
+        # Helper file constructors are runtime-only (only run when
+        # instantiated from enable()), so only flag in extension.js
         is_extension_js = os.path.basename(filepath) == 'extension.js'
-        ctor_lines = extract_constructor_lines(lines)
-        for lineno, line in ctor_lines:
-            if is_skip_line(line):
-                continue
-            if SHELL_GLOBALS.search(line):
-                violations.append(f"{rel}:{lineno}")
-            elif is_extension_js and GOBJECT_CONSTRUCTORS.search(line):
-                violations.append(f"{rel}:{lineno}")
+        if is_extension_js:
+            ctor_lines = extract_constructor_lines(lines)
+            for lineno, line in ctor_lines:
+                if is_skip_line(line):
+                    continue
+                if SHELL_GLOBALS.search(line):
+                    violations.append(f"{rel}:{lineno}")
+                elif GOBJECT_CONSTRUCTORS.search(line):
+                    violations.append(f"{rel}:{lineno}")
 
     if violations:
         for loc in violations:

skills/ego-lint/scripts/check-lifecycle.py

@@ -123,8 +123,13 @@ def check_signal_balance(ext_dir):
                 connect_objects += 1
             elif re.search(r'\.connectSmart\s*\(', line):
                 smart_connects += 1
-            elif re.search(r'\.connect\s*\(', line) and not re.search(r'\.disconnect', line):
-                pure_connects += 1
+            elif re.search(r"\.connect\s*\(\s*['\"]", line) and not re.search(r'\.disconnect', line):
+                if re.search(r"\.connect\s*\(\s*['\"]destroy['\"]", line):
+                    pass  # 'destroy' signal — inherently self-cleaning
+                elif not re.search(r'this[._]', line):
+                    pass  # local variable signal — inherently scoped
+                else:
+                    pure_connects += 1
             if re.search(r'\.disconnectObject\s*\(', line):
                 pass  # auto-cleanup
             elif re.search(r'\.disconnectSmart\s*\(', line):

skills/ego-lint/scripts/ego-lint.sh

@@ -421,9 +421,12 @@ for f in "$EXT_DIR"/*.js; do
         continue
     fi
 
-    # Check for any line > 500 chars (strong minification signal)
-    if awk 'length > 500 { found=1; exit } END { exit !found }' "$f" 2>/dev/null; then
-        minified_files+="  $rel_path (lines > 500 chars)"$'\n'
+    # Check for lines > 500 chars — need 3+ such lines to flag as minified.
+    # A single long line (e.g., keyboard constant chain) in an otherwise
+    # readable file is not minification.
+    long_line_count=$(awk 'length > 500 { n++ } END { print n+0 }' "$f" 2>/dev/null || true)
+    if [[ "$long_line_count" -ge 3 ]]; then
+        minified_files+="  $rel_path ($long_line_count lines > 500 chars)"$'\n'
     fi
 done
 if [[ -d "$EXT_DIR/lib" ]]; then
@@ -433,8 +436,9 @@ if [[ -d "$EXT_DIR/lib" ]]; then
             minified_files+="  $rel_path (webpack bundle)"$'\n'
             continue
         fi
-        if awk 'length > 500 { found=1; exit } END { exit !found }' "$f" 2>/dev/null; then
-            minified_files+="  $rel_path (lines > 500 chars)"$'\n'
+        long_line_count=$(awk 'length > 500 { n++ } END { print n+0 }' "$f" 2>/dev/null || true)
+        if [[ "$long_line_count" -ge 3 ]]; then
+            minified_files+="  $rel_path ($long_line_count lines > 500 chars)"$'\n'
         fi
     done < <(find "$EXT_DIR/lib" -name '*.js' -print0 2>/dev/null)
 fi

tests/assertions/signal-balance-fp.sh

@@ -0,0 +1,23 @@
+# --- signal-non-gobject (Sub-issue A: non-signal .connect() not counted) ---
+echo "=== signal-non-gobject ==="
+run_lint "signal-non-gobject@test"
+assert_exit_code "exits with 0 (no failures)" 0
+assert_output_contains "signal balance OK" "\[PASS\].*lifecycle/signal-balance"
+assert_output_not_contains "no signal imbalance warning" "\[WARN\].*lifecycle/signal-balance"
+echo ""
+
+# --- signal-destroy-connect (Sub-issue B: destroy signal not counted) ---
+echo "=== signal-destroy-connect ==="
+run_lint "signal-destroy-connect@test"
+assert_exit_code "exits with 0 (no failures)" 0
+assert_output_contains "signal balance OK" "\[PASS\].*lifecycle/signal-balance"
+assert_output_not_contains "no signal imbalance warning" "\[WARN\].*lifecycle/signal-balance"
+echo ""
+
+# --- signal-local-variable (Sub-issue C: local-variable signal not counted) ---
+echo "=== signal-local-variable ==="
+run_lint "signal-local-variable@test"
+assert_exit_code "exits with 0 (no failures)" 0
+assert_output_contains "signal balance OK" "\[PASS\].*lifecycle/signal-balance"
+assert_output_not_contains "no signal imbalance warning" "\[WARN\].*lifecycle/signal-balance"
+echo ""

tests/fixtures/gnome49-compat@test/extension.js

@@ -9,6 +9,15 @@ export default class Gnome49Test extends Extension {
         this._tap = new Clutter.TapAction();
     }
 
+    // Ternary version-compat guard: should NOT trigger R-VER49-08/11
+    _maximizeCompat(window) {
+        window.get_maximized ? window.maximize(Meta.MaximizeFlags.BOTH) : window.maximize();
+    }
+
+    _unmaximizeCompat(window) {
+        window.get_maximized ? window.unmaximize(Meta.MaximizeFlags.BOTH) : window.unmaximize();
+    }
+
     disable() {
         this._click = null;
         this._tap = null;

tests/fixtures/init-time-safety@test/LICENSE

@@ -0,0 +1 @@
+SPDX-License-Identifier: GPL-2.0-or-later

tests/fixtures/init-time-safety@test/extension.js

@@ -0,0 +1,20 @@
+import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';
+import * as Main from 'resource:///org/gnome/shell/ui/main.js';
+
+// TRUE VIOLATION: module-scope Shell global access
+const primaryIdx = Main.layoutManager.primaryIndex;
+
+// OK: arrow function definition is lazy (body not executed at module scope)
+const getMonitors = () => Main.layoutManager.monitors;
+
+export default class InitTimeTest extends Extension {
+    enable() {
+        // OK: Shell globals inside enable()
+        Main.panel.addToStatusArea('test', this);
+        this._monitors = getMonitors();
+    }
+
+    disable() {
+        this._monitors = null;
+    }
+}