fix(ego-lint): suppress fix text for multi-version extensions (#8)

fix(ego-lint): suppress fix text for multi-version extensions (#7)

Add fix-min-version field to pattern rules that gates the fix suggestion
based on the extension's minimum declared shell-version. R-VER48-04/04b
still warn about the deprecated vertical property, but omit the
"use orientation" fix when the extension targets GNOME <=46 where
orientation is unavailable.

Closes #7

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

Author: ZviBaratz

CLAUDE.md

@@ -44,7 +44,7 @@ bash skills/ego-lint/scripts/ego-lint.sh tests/fixtures/<fixture-name>
 `ego-lint.sh` is the main orchestrator. It uses a three-tier rule system (pattern → structural → semantic) and delegates to sub-scripts via `run_subscript`:
 
 - `rules/patterns.yaml` — Tier 1 pattern rules (124 regex-based, declarative rules). Note: at project root, not under `skills/ego-lint/`
-- `apply-patterns.py` — Tier 1 pattern engine (inline YAML parser, no PyYAML dependency). Supports `guard-pattern` + `guard-window` (sliding `deque` lookback), `replacement-pattern`, `exclude-dirs`, version-gating
+- `apply-patterns.py` — Tier 1 pattern engine (inline YAML parser, no PyYAML dependency). Supports `guard-pattern` + `guard-window` (sliding `deque` lookback), `replacement-pattern`, `exclude-dirs`, version-gating, `fix-min-version` (suppresses fix text when extension min shell-version is below threshold)
 - `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

rules/README.md

@@ -176,6 +176,28 @@ if (global.compositor) {
 - Only use when the default 1-line lookback is insufficient — most guards are on the same or previous line
 - Keep the window as small as practical to avoid false suppressions
 
+### Fix Version Gating (`fix-min-version`)
+
+When a deprecation rule suggests a fix that only works on newer GNOME versions, use `fix-min-version` to suppress the fix text for extensions whose minimum shell-version is below the threshold. The warning still fires (developers should know about deprecations), but the fix suggestion is omitted when applying it would break backward compatibility.
+
+```yaml
+- id: R-VER48-04
+  pattern: "\\.vertical\\s*="
+  scope: ["*.js"]
+  severity: advisory
+  message: "St.Widget.vertical deprecated in GNOME 48; use orientation (available since GNOME 47; keep vertical for GNOME <=46 compat)"
+  fix: "Use {orientation: Clutter.Orientation.VERTICAL} instead of {vertical: true}"
+  min-version: 48
+  fix-min-version: 47
+```
+
+For an extension with `shell-version: ["46", "47", "48"]` (min_shell=46), the fix text is suppressed because 46 < 47. For an extension targeting only `["48"]` (min_shell=48), the fix text is shown because 48 >= 47.
+
+**Guidelines:**
+- Set `fix-min-version` to the GNOME version where the replacement API was introduced
+- Only use when the fix would break older versions in the extension's declared range
+- The warning message should include the compat note inline (e.g., "keep vertical for GNOME <=46 compat")
+
 ## Inline Suppression
 
 Add `ego-lint-ignore` comments to suppress specific findings on a per-line basis.

rules/patterns.yaml

@@ -932,19 +932,21 @@
   pattern: "\\.vertical\\s*="
   scope: ["*.js"]
   severity: advisory
-  message: "St.Widget.vertical property deprecated in GNOME 48; use orientation: Clutter.Orientation.VERTICAL"
+  message: "St.Widget.vertical property deprecated in GNOME 48; use orientation: Clutter.Orientation.VERTICAL (available since GNOME 47; keep vertical for GNOME <=46 compat)"
   category: version-compat
   fix: "Use {orientation: Clutter.Orientation.VERTICAL} instead of {vertical: true}"
   min-version: 48
+  fix-min-version: 47
 
 - id: R-VER48-04b
   pattern: "vertical:\\s*(true|false)"
   scope: ["*.js"]
   severity: advisory
-  message: "vertical property in constructor config removed in GNOME 48; use orientation: Clutter.Orientation.VERTICAL"
+  message: "vertical property in constructor config deprecated in GNOME 48; use orientation: Clutter.Orientation.VERTICAL (available since GNOME 47; keep vertical for GNOME <=46 compat)"
   category: version-compat
   fix: "Replace {vertical: true} with {orientation: Clutter.Orientation.VERTICAL}"
   min-version: 48
+  fix-min-version: 47
 
 - id: R-VER48-05
   pattern: "\\bShell\\.SnippetHook\\b"

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

@@ -1811,10 +1811,10 @@ Rules for APIs removed or changed in specific GNOME Shell versions. These rules
 
 ### R-VER48-04: St.Widget.vertical deprecated
 - **Severity**: advisory
-- **Checked by**: apply-patterns.py (min-version: 48)
+- **Checked by**: apply-patterns.py (min-version: 48, fix-min-version: 47)
 - **Rule**: The `.vertical` property on St widgets is deprecated in GNOME 48.
-- **Rationale**: Will be removed around GNOME 50. Use the orientation property instead.
-- **Fix**: Use `{orientation: Clutter.Orientation.VERTICAL}` instead of `{vertical: true}`.
+- **Rationale**: Will be removed around GNOME 50. The `orientation` property replacement is available since GNOME 47. For multi-version extensions targeting GNOME <=46, the fix cannot be applied unconditionally.
+- **Fix**: Use `{orientation: Clutter.Orientation.VERTICAL}` instead of `{vertical: true}`. Fix text is suppressed when the extension's minimum shell-version is below 47.
 
 ### R-VER48-05: Shell.SnippetHook removed
 - **Severity**: blocking
@@ -2460,10 +2460,10 @@ Rules for APIs removed or changed in specific GNOME Shell versions. These rules
 
 ### R-VER48-04b: vertical property in constructor config
 - **Severity**: advisory
-- **Checked by**: apply-patterns.py (min-version: 48)
-- **Rule**: `vertical: true/false` in constructor configuration objects was removed in GNOME 48.
-- **Rationale**: GNOME 48 removed the `vertical` shorthand property from St.BoxLayout and other container constructors. Extensions targeting GNOME 48+ must use the `orientation` property with `Clutter.Orientation.VERTICAL` or `Clutter.Orientation.HORIZONTAL`.
-- **Fix**: Replace `{vertical: true}` with `{orientation: Clutter.Orientation.VERTICAL}`.
+- **Checked by**: apply-patterns.py (min-version: 48, fix-min-version: 47)
+- **Rule**: `vertical: true/false` in constructor configuration objects is deprecated in GNOME 48.
+- **Rationale**: GNOME 48 deprecated the `vertical` shorthand property from St.BoxLayout and other container constructors. The `orientation` property replacement is available since GNOME 47. For multi-version extensions targeting GNOME <=46, the fix cannot be applied unconditionally.
+- **Fix**: Replace `{vertical: true}` with `{orientation: Clutter.Orientation.VERTICAL}`. Fix text is suppressed when the extension's minimum shell-version is below 47.
 
 ---
 

skills/ego-lint/scripts/apply-patterns.py

@@ -225,6 +225,15 @@ def validate_rules(rules_file):
                 print(f"ERROR: {rid}: guard-window must be an integer, got '{gw}'")
                 errors += 1
 
+        # Check fix-min-version validity
+        fix_min = rule.get('fix-min-version')
+        if fix_min is not None:
+            try:
+                int(fix_min)
+            except (ValueError, TypeError):
+                print(f"ERROR: {rid}: fix-min-version must be an integer, got '{fix_min}'")
+                errors += 1
+
     if errors:
         print(f"\n{errors} error(s) found in {len(rules)} rules")
         return 1
@@ -251,6 +260,7 @@ def main():
 
     rules = parse_rules(rules_file)
     shell_versions = _get_shell_versions(ext_dir)
+    min_shell = min(shell_versions) if shell_versions else None
 
     for rule in rules:
         rid = rule.get('id', '?')
@@ -339,6 +349,13 @@ def main():
                                 found = True
                             else:
                                 fix = rule.get('fix', '')
+                                fix_min_ver = rule.get('fix-min-version')
+                                if fix and fix_min_ver is not None and min_shell is not None:
+                                    try:
+                                        if min_shell < int(fix_min_ver):
+                                            fix = ''
+                                    except (ValueError, TypeError):
+                                        pass
                                 if fix:
                                     print(f"{status}|{rid}|{rel}:{lineno}: {message}|fix: {fix}")
                                 else:
@@ -351,6 +368,13 @@ def main():
         if deduplicate and dedup_files:
             files_list = ', '.join(sorted(dedup_files))
             fix = rule.get('fix', '')
+            fix_min_ver = rule.get('fix-min-version')
+            if fix and fix_min_ver is not None and min_shell is not None:
+                try:
+                    if min_shell < int(fix_min_ver):
+                        fix = ''
+                except (ValueError, TypeError):
+                    pass
             summary = f"{message} in {len(dedup_files)} file(s): {files_list}"
             if fix:
                 print(f"{status}|{rid}|{summary}|fix: {fix}")

tests/assertions/multiversion-compat.sh

@@ -0,0 +1,11 @@
+# fix-min-version gating tests (R-VER48-04/04b with multi-version extensions)
+# Sourced by run-tests.sh
+
+echo "=== multiversion-vertical ==="
+run_lint "multiversion-vertical@test"
+assert_exit_code "exits with 0 (advisory only)" 0
+assert_output_contains "warns on vertical assignment" "\[WARN\].*R-VER48-04 "
+assert_output_contains "warns on vertical constructor" "\[WARN\].*R-VER48-04b"
+assert_output_contains "message mentions compat" "keep vertical for GNOME"
+assert_output_not_contains "no fix text when min-shell below fix-min-version" "fix:.*orientation"
+echo ""

tests/fixtures/multiversion-vertical@test/LICENSE

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

tests/fixtures/multiversion-vertical@test/extension.js

@@ -0,0 +1,15 @@
+import St from 'gi://St';
+import Clutter from 'gi://Clutter';
+import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';
+
+export default class MultiVersionExtension extends Extension {
+    enable() {
+        this._box = new St.BoxLayout({vertical: true});
+        this._box.vertical = false;
+    }
+
+    disable() {
+        this._box.destroy();
+        this._box = null;
+    }
+}

tests/fixtures/multiversion-vertical@test/metadata.json

@@ -0,0 +1,7 @@
+{
+    "uuid": "multiversion-vertical@test",
+    "name": "Multiversion Vertical Test",
+    "description": "Tests fix-min-version gating for R-VER48-04/04b",
+    "shell-version": ["46", "47", "48"],
+    "url": "https://example.com"
+}