fix(ego-lint): exempt isLocked guard from impossible-state and session-modes checks (#31)

## Summary

Field test #10 (Just Perfection) revealed that `sessionMode.isLocked` is
always a guard pattern — reading lock state to decide behavior, not
evidence of lock screen functionality. Extensions like Just Perfection
use it defensively to avoid modifying UI when locked.

- **impossible-state**: Remove `isLocked` from check, keep `currentMode`
comparisons (both `===` and `!==`)
- **session-modes-consistency**: Narrow regex to only flag
`sessionMode.currentMode` references
- **comment-density**: Raise threshold from 40% to 50% — well-documented
JSDoc code hits 40% legitimately

Closes #27

## Test plan

- [x] New fixture `islocked-guard@test` with `sessionMode.isLocked`
guard
- [x] Updated `ai-slop@test` to use `currentMode !== 'unlock-dialog'`
- [x] 455 tests pass (452 baseline + 3 new)
- [ ] Verify no regressions on other field-tested extensions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: ZviBaratz

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

@@ -921,9 +921,9 @@ Heuristic rules that detect code patterns commonly seen in AI-generated or over-
 ### R-QUAL-02: Impossible state checks
 - **Severity**: advisory
 - **Checked by**: check-quality.py
-- **Rule**: Extension code should not check for states that are impossible given its configuration. For example, checking `Main.sessionMode.isLocked` without declaring `unlock-dialog` in `session-modes`.
-- **Rationale**: If the extension does not declare `unlock-dialog` in `session-modes`, it is never active on the lock screen, so checking lock state is dead code. This pattern is common in AI-generated extensions that copy-paste lock-screen handling without understanding when it applies.
-- **Fix**: Either add `"unlock-dialog"` to `session-modes` in `metadata.json` (if lock-screen support is intended) or remove the lock-state checking code.
+- **Rule**: Extension code should not check for states that are impossible given its configuration. For example, comparing `Main.sessionMode.currentMode` with `'unlock-dialog'` without declaring `unlock-dialog` in `session-modes`. Note: `sessionMode.isLocked` is exempt — reading lock state is always a defensive guard pattern, not evidence of lock screen functionality.
+- **Rationale**: If the extension does not declare `unlock-dialog` in `session-modes`, it is never active on the lock screen, so checking `currentMode` against lock-screen values is dead code. This pattern is common in AI-generated extensions that copy-paste lock-screen handling without understanding when it applies.
+- **Fix**: Either add `"unlock-dialog"` to `session-modes` in `metadata.json` (if lock-screen support is intended) or remove the `currentMode` comparison code.
 
 ### R-QUAL-03: Over-engineered async coordination
 - **Severity**: advisory
@@ -1561,7 +1561,7 @@ destroy() {
 ### R-QUAL-11: Comment Density
 - **Severity**: advisory
 - **Checked by**: check-quality.py
-- **Rule**: Flags files where >40% of lines (after first 10) are comments.
+- **Rule**: Flags files where >50% of lines (after first 10) are comments.
 - **Rationale**: Excessive comments explaining obvious code is a strong AI slop signal.
 - **Fix**: Remove redundant comments. Only keep comments that explain non-obvious logic or API quirks.
 - **Tested by**: `tests/fixtures/quality-signals@test/`
@@ -1952,7 +1952,7 @@ Rules for APIs removed or changed in specific GNOME Shell versions. These rules
 ### metadata/session-modes-consistency: SessionMode usage without declaration
 - **Severity**: advisory
 - **Checked by**: check-metadata.py
-- **Rule**: Warns if the extension code references `Main.sessionMode.currentMode` or `sessionMode.isLocked` but `metadata.json` does not declare `session-modes` with `unlock-dialog`.
+- **Rule**: Warns if the extension code references `Main.sessionMode.currentMode` but `metadata.json` does not declare `session-modes` with `unlock-dialog`. Note: `sessionMode.isLocked` is exempt — reading lock state is a defensive guard, not evidence of lock screen usage.
 - **Rationale**: Code that checks session mode without the proper declaration is either dead code (the extension won't run in lock screen mode) or a misunderstanding of the lifecycle.
 - **Fix**: Either add `"session-modes": ["user", "unlock-dialog"]` to metadata.json, or remove the session mode checks from the code.
 

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

@@ -354,7 +354,9 @@ def check_session_modes_consistency(meta, ext_dir):
                "session-modes includes 'unlock-dialog'")
         return
 
-    session_mode_re = re.compile(r"sessionMode\.(currentMode|isLocked)")
+    # Only flag currentMode checks — isLocked is always a guard pattern
+    # (reading lock state to decide behavior, not evidence of lock screen usage)
+    session_mode_re = re.compile(r"sessionMode\.currentMode")
     found = []
     for root, _dirs, files in os.walk(ext_dir):
         for fname in files:

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

@@ -5,7 +5,7 @@
 
 Performs structural analysis that goes beyond simple pattern matching:
   - Excessive try-catch density
-  - Impossible state checks (isLocked without lock session-mode)
+  - Impossible state checks (currentMode unlock-dialog without lock session-mode)
   - Over-engineered async coordination (_pendingDestroy + _initializing)
   - Module-level mutable state
   - Empty catch blocks
@@ -114,7 +114,7 @@ def check_try_catch_density(ext_dir, js_files):
 
 
 def check_impossible_state(ext_dir, js_files):
-    """R-QUAL-02: Flag isLocked/unlock-dialog checks without matching session-modes."""
+    """R-QUAL-02: Flag currentMode unlock-dialog checks without matching session-modes."""
     session_modes = get_session_modes(ext_dir)
     # If session-modes absent or ["user"], extension doesn't run on lock screen
     has_lock = (isinstance(session_modes, list) and
@@ -130,12 +130,10 @@ def check_impossible_state(ext_dir, js_files):
         rel = os.path.relpath(filepath, ext_dir)
         with open(filepath, encoding='utf-8', errors='replace') as f:
             for lineno, line in enumerate(f, 1):
-                if re.search(r'sessionMode\.isLocked', line):
-                    result("WARN", "quality/impossible-state",
-                           f"{rel}:{lineno}: checks isLocked but extension "
-                           f"does not run in lock screen")
-                    found = True
-                elif re.search(r"currentMode\s*===?\s*['\"]unlock-dialog['\"]", line):
+                # sessionMode.isLocked is always a guard (reading lock state
+                # to decide behavior) — not evidence of lock screen mode usage.
+                # Only flag currentMode === 'unlock-dialog' checks.
+                if re.search(r"currentMode\s*[!=]==?\s*['\"]unlock-dialog['\"]", line):
                     result("WARN", "quality/impossible-state",
                            f"{rel}:{lineno}: checks for unlock-dialog but "
                            f"extension does not declare this session-mode")
@@ -699,7 +697,7 @@ def check_comment_density(ext_dir, js_files):
                 code_lines += 1
 
         total = comment_lines + code_lines
-        if total > 0 and comment_lines / total > 0.4:
+        if total > 0 and comment_lines / total > 0.5:
             result("WARN", "quality/comment-density",
                    f"{rel}: {comment_lines}/{total} lines are comments "
                    f"({comment_lines * 100 // total}%) — may indicate AI-generated verbose comments")

tests/assertions/islocked-guard.sh

@@ -0,0 +1,9 @@
+# Field test #10: isLocked guard exemption (closes #27)
+
+# --- islocked-guard (sessionMode.isLocked as guard, not lock screen) ---
+echo "=== islocked-guard ==="
+run_lint "islocked-guard@test"
+assert_exit_code "exits with 0" 0
+assert_output_not_contains "no impossible-state for isLocked guard" "\[WARN\].*quality/impossible-state"
+assert_output_not_contains "no session-modes-consistency for isLocked" "\[WARN\].*session-modes-consistency"
+echo ""

tests/fixtures/ai-slop@test/extension.js

@@ -15,7 +15,7 @@ export default class AiSlopExtension extends Extension {
         this._pendingDestroy = false;
         this._indicator = null;
 
-        if (!Main.sessionMode.isLocked && this._indicator === null)
+        if (Main.sessionMode.currentMode !== 'unlock-dialog' && this._indicator === null)
             this._initAsync();
     }
 

tests/fixtures/islocked-guard@test/LICENSE

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

tests/fixtures/islocked-guard@test/extension.js

@@ -0,0 +1,21 @@
+import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';
+import * as Main from 'resource:///org/gnome/shell/ui/main.js';
+
+export default class TestExtension extends Extension {
+    enable() {
+        if (!this._isLocked()) {
+            this._applySettings();
+        }
+    }
+
+    disable() {
+        this._revertSettings();
+    }
+
+    _isLocked() {
+        return Main.sessionMode.isLocked;
+    }
+
+    _applySettings() {}
+    _revertSettings() {}
+}

tests/fixtures/islocked-guard@test/metadata.json

@@ -0,0 +1,7 @@
+{
+    "uuid": "islocked-guard@test",
+    "name": "Test isLocked Guard",
+    "description": "Tests that sessionMode.isLocked guard is not flagged",
+    "shell-version": ["48"],
+    "url": "https://example.com"
+}