fix(ego-lint): reduce Media Controls false positives (#23)

## Summary

- **onDestroy() recognized as cleanup**: `build-resource-graph.py` now
detects `onDestroy()` alongside `destroy()`, `disable()`, and
`_destroy*()` — eliminates 45 FP WARNs from Media Controls
- **Provenance threshold lowered 4→3**: Score 3 means strong
hand-written indicators (domain vocabulary, nontrivial algorithms). AI
code scores 1-2. Eliminates 173 FP R-SLOP-01/02 WARNs

Closes #17

## Test plan

- [x] New fixture: `on-destroy-cleanup@test` with widget using
`onDestroy()` via `this.connect("destroy", ...)`
- [x] Assertion: no `resource-tracking/no-destroy-method` for widget
with onDestroy
- [x] `bash tests/run-tests.sh` passes (512 assertions)

🤖 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

@@ -831,7 +831,7 @@ Rules that detect patterns commonly found in AI-generated extensions. These are
 - **Rule**: JSDoc comments should not use TypeScript-style `@param {Type} name` annotations.
 - **Rationale**: GNOME Shell extensions are plain JavaScript (not TypeScript). JSDoc type annotations in the `{Type}` format are a strong signal that code was generated by an AI trained primarily on TypeScript codebases. EGO reviewers recognize this pattern.
 - **Fix**: Remove type annotations from JSDoc comments, or remove JSDoc entirely if the code is self-documenting. GJS does not process JSDoc types.
-- **Provenance suppression**: When `quality/code-provenance` reports a score >= 4 (strong hand-written indicators), R-SLOP-01 warnings are automatically suppressed. High-provenance code uses JSDoc as intentional documentation, not AI slop. A `provenance/jsdoc-suppressed` PASS line is emitted instead.
+- **Provenance suppression**: When `quality/code-provenance` reports a score >= 3 (moderate-to-high hand-written indicators), R-SLOP-01 warnings are automatically suppressed. Hand-written code uses JSDoc as intentional documentation, not AI slop. A `provenance/jsdoc-suppressed` PASS line is emitted instead.
 
 #### Example
 
@@ -862,7 +862,7 @@ _updateIndicator(level, charging, icon) {
 - **Rule**: JSDoc comments should not use TypeScript-style `@returns {Type}` annotations.
 - **Rationale**: Same as R-SLOP-01. `@returns {Type}` is a TypeScript convention that has no effect in GJS and signals AI-generated code.
 - **Fix**: Remove `@returns {Type}` annotations from JSDoc comments.
-- **Provenance suppression**: Same as R-SLOP-01 — suppressed when provenance score >= 4.
+- **Provenance suppression**: Same as R-SLOP-01 — suppressed when provenance score >= 3.
 
 #### Example
 
@@ -2011,8 +2011,8 @@ Rules for APIs removed or changed in specific GNOME Shell versions. These rules
 ### resource-tracking/no-destroy-method
 - **Severity**: advisory
 - **Checked by**: check-resources.py → build-resource-graph.py
-- **Rule**: Module creates resources but has no `destroy()` or `disable()` method for cleanup.
-- **Fix**: Add a `destroy()` method that cleans up all resources.
+- **Rule**: Module creates resources but has no cleanup method (`destroy()`, `disable()`, or `onDestroy()`) for cleanup.
+- **Fix**: Add a `destroy()` method that cleans up all resources, or use `onDestroy()` connected via `this.connect('destroy', this.onDestroy.bind(this))`.
 
 ### resource-tracking/destroy-not-called
 - **Severity**: advisory

skills/ego-lint/scripts/build-resource-graph.py

@@ -329,6 +329,10 @@ def scan_file(file_path, ext_dir):
     has_private_destroy = bool(re.search(
         r'(?:^|\s)_destroy\w*\s*\([^)]*\)\s*\{', content, re.MULTILINE
     ))
+    # Detect onDestroy() — common pattern via this.connect("destroy", this.onDestroy.bind(this))
+    has_on_destroy = bool(re.search(
+        r'(?:^|\s)onDestroy\s*\([^)]*\)\s*\{', content, re.MULTILINE
+    ))
 
     return {
         'rel': rel,
@@ -339,6 +343,7 @@ def scan_file(file_path, ext_dir):
         'has_destroy': has_destroy,
         'has_disable': has_disable,
         'has_private_destroy': has_private_destroy,
+        'has_on_destroy': has_on_destroy,
         'child_refs': child_refs,
         'content': content,
     }
@@ -436,9 +441,9 @@ def detect_orphans(file_scans, ownership):
     """Detect orphaned resources in files that are owned by other files.
 
     An orphan is a resource created in a child module where:
-    1. No matching cleanup exists in that module's destroy() method, OR
-    2. The module has no destroy() method but creates resources, OR
-    3. The module's destroy() is never called by its parent.
+    1. The module has no cleanup method (destroy/disable/onDestroy) but creates resources, OR
+    2. The module has a cleanup method but its parent never calls it, OR
+    3. The cleanup method exists and is called, but specific resources aren't cleaned up.
 
     Only flags resources in files that ARE owned by another file.
     """
@@ -463,7 +468,8 @@ def detect_orphans(file_scans, ownership):
         has_destroy = scan['has_destroy']
         has_disable = scan['has_disable']
         has_private_destroy = scan['has_private_destroy']
-        has_cleanup_method = has_destroy or has_disable or has_private_destroy
+        has_on_destroy = scan['has_on_destroy']
+        has_cleanup_method = has_destroy or has_disable or has_private_destroy or has_on_destroy
 
         if not creates:
             continue
@@ -486,27 +492,27 @@ def detect_orphans(file_scans, ownership):
                         parent_calls_destroy = True
                         break
 
-        # Case 1: Module creates resources but has no destroy/disable method
+        # Case 1: Module creates resources but has no cleanup method
         if not has_cleanup_method:
             for c in creates:
                 orphans.append({
                     'file': rel,
                     'line': c['line'],
                     'type': c['type'],
                     'pattern': c['pattern'],
-                    'reason': f"no destroy()/disable() method in {rel}",
+                    'reason': f"no cleanup method (destroy/disable/onDestroy) in {rel}",
                 })
             continue
 
-        # Case 2: Module has destroy() but parent never calls it
+        # Case 2: Module has cleanup method but parent never calls it
         if not parent_calls_destroy:
             for c in creates:
                 orphans.append({
                     'file': rel,
                     'line': c['line'],
                     'type': c['type'],
                     'pattern': c['pattern'],
-                    'reason': f"parent does not call destroy() on {rel}",
+                    'reason': f"parent does not call cleanup method on {rel}",
                 })
             continue
 
@@ -517,7 +523,7 @@ def detect_orphans(file_scans, ownership):
         # releasing references even when the resource auto-cleans itself
         nulled_refs = set()
         content = scan['content']
-        for method_name in ('destroy', 'disable', '_destroy'):
+        for method_name in ('destroy', 'disable', '_destroy', 'onDestroy'):
             mb = find_method_body(content, method_name)
             if mb:
                 _, _, body = mb

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

@@ -52,13 +52,13 @@ def classify_orphan(orphan):
     file_path = orphan.get('file', '')
     line = orphan.get('line', '?')
 
-    # Case 1: No destroy/disable method at all
-    if 'no destroy()/disable() method' in reason:
+    # Case 1: No cleanup method at all (destroy/disable/onDestroy)
+    if 'no cleanup method' in reason:
         detail = f"{file_path}:{line} — {reason}"
         return 'resource-tracking/no-destroy-method', detail
 
-    # Case 2: Parent doesn't call destroy
-    if 'parent does not call destroy()' in reason:
+    # Case 2: Parent doesn't call cleanup method
+    if 'parent does not call cleanup method' in reason:
         detail = f"{file_path}:{line} — {reason}"
         return 'resource-tracking/destroy-not-called', detail
 

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

@@ -583,8 +583,10 @@ run_subscript "$SCRIPT_DIR/check-package.sh"
 # ---------------------------------------------------------------------------
 # Provenance-gated WARN suppression
 # ---------------------------------------------------------------------------
-# When code provenance is high (score >= 4), JSDoc annotations (R-SLOP-01/02)
-# are intentional documentation, not AI slop signals. Suppress them post-hoc.
+# When code provenance is moderate-to-high (score >= 3), JSDoc annotations
+# (R-SLOP-01/02) are intentional documentation, not AI slop signals. Score 3
+# means strong hand-written indicators (domain vocabulary, nontrivial algorithms).
+# AI-generated code typically scores 1-2. Suppress JSDoc warnings post-hoc.
 # Future: move provenance awareness into apply-patterns.py for inline gating.
 
 provenance_score=0
@@ -595,8 +597,8 @@ if provenance_line=$(grep 'quality/code-provenance' "$RESULTS_FILE" 2>/dev/null)
 fi
 
 deferred_count=${#DEFERRED_SLOP_JSDOC[@]}
-if [[ "$provenance_score" -ge 4 && "$deferred_count" -gt 0 ]]; then
-    # Suppress deferred R-SLOP-01/02 WARNs (high provenance = intentional JSDoc)
+if [[ "$provenance_score" -ge 3 && "$deferred_count" -gt 0 ]]; then
+    # Suppress deferred R-SLOP-01/02 WARNs (moderate-to-high provenance = intentional JSDoc)
     WARN_COUNT=$((WARN_COUNT - deferred_count))
     PASS_COUNT=$((PASS_COUNT + 1))
     print_result "PASS" "provenance/jsdoc-suppressed" \

tests/fixtures/on-destroy-cleanup@test/LICENSE

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

tests/fixtures/on-destroy-cleanup@test/extension.js

@@ -0,0 +1,15 @@
+import GLib from 'gi://GLib';
+import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';
+
+import TestWidget from './widget.js';
+
+export default class TestExtension extends Extension {
+    enable() {
+        this._widget = new TestWidget();
+    }
+
+    disable() {
+        this._widget.destroy();
+        this._widget = null;
+    }
+}

tests/fixtures/on-destroy-cleanup@test/metadata.json

@@ -0,0 +1,7 @@
+{
+    "uuid": "on-destroy-cleanup@test",
+    "name": "Test onDestroy Cleanup",
+    "description": "Test onDestroy() recognized as cleanup method",
+    "shell-version": ["48"],
+    "url": "https://example.com"
+}

tests/fixtures/on-destroy-cleanup@test/widget.js

@@ -0,0 +1,25 @@
+import GObject from 'gi://GObject';
+import GLib from 'gi://GLib';
+import St from 'gi://St';
+
+class TestWidget extends St.BoxLayout {
+    constructor() {
+        super();
+        this._sourceId = GLib.timeout_add_seconds(GLib.PRIORITY_DEFAULT, 5, () => {
+            return GLib.SOURCE_CONTINUE;
+        });
+        this.connect('destroy', this.onDestroy.bind(this));
+    }
+
+    onDestroy() {
+        if (this._sourceId) {
+            GLib.Source.remove(this._sourceId);
+            this._sourceId = null;
+        }
+    }
+}
+
+export default GObject.registerClass(
+    { GTypeName: 'TestWidget' },
+    TestWidget,
+);

tests/run-tests.sh

@@ -626,6 +626,14 @@ assert_output_contains "metadata.json found in src/" "\[PASS\].*file-structure/m
 assert_output_not_contains "no metadata/exists FAIL" "\[FAIL\].*metadata/exists"
 echo ""
 
+# --- on-destroy-cleanup (onDestroy recognized as cleanup) ---
+echo "=== on-destroy-cleanup ==="
+run_lint "on-destroy-cleanup@test"
+assert_exit_code "exits with 0 (no blocking issues)" 0
+assert_output_not_contains "no no-destroy-method for widget with onDestroy" "\[WARN\].*resource-tracking/no-destroy-method.*widget"
+assert_output_contains "resource tracking ran" "(PASS|WARN|FAIL).*resource-tracking"
+echo ""
+
 # Extended assertion files (auto-sourced from assertions/ directory)
 ASSERTIONS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/assertions"
 for assertion_file in "$ASSERTIONS_DIR"/*.sh; do