add linting checks using ruff and make lint related refactors

Author: thedavidwhiteside

.github/workflows/test.yml

@@ -7,8 +7,27 @@ on:
     branches: [main, develop]
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Lint (ruff check)
+        run: ruff check hooks/ tests/ --output-format github
+
+      - name: Format (ruff format)
+        run: ruff format hooks/ tests/ --check
+
   test:
     runs-on: ubuntu-latest
+    needs: lint
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12"]

hooks/enforce_quota.py

@@ -15,12 +15,10 @@
 """
 
 import json
-import sys
 import os
+import sys
 from datetime import date, timedelta
-from pathlib import Path
 
-sys.path.insert(0, str(Path(__file__).parent))
 from quota_store import QuotaStore
 
 WARN_CRITICAL = int(os.environ.get("TOKEN_QUOTA_WARN_CRITICAL", 95))
@@ -42,14 +40,7 @@ def main():
     pct_daily = (used_daily / effective_daily) * 100 if effective_daily > 0 else 0
 
     if used_daily >= effective_daily:
-        result = {
-            "decision": "block",
-            "reason": (
-                f"Daily token quota exceeded.\n"
-                f"Used:  {used_daily:,} / {effective_daily:,} tokens ({pct_daily:.1f}%)\n"
-                f"Quota resets at midnight. Edit TOKEN_QUOTA_DAILY to change the limit."
-            )
-        }
+        result = {"decision": "block", "reason": (f"Daily token quota exceeded.\nUsed:  {used_daily:,} / {effective_daily:,} tokens ({pct_daily:.1f}%)\nQuota resets at midnight. Edit TOKEN_QUOTA_DAILY to change the limit.")}
         print(json.dumps(result))
         sys.exit(0)
 
@@ -59,14 +50,7 @@ def main():
         effective_weekly = store.weekly_limit + snooze
         if used_weekly >= effective_weekly:
             pct = (used_weekly / effective_weekly) * 100
-            result = {
-                "decision": "block",
-                "reason": (
-                    f"Weekly token quota exceeded (rolling 7-day window).\n"
-                    f"Used:  {used_weekly:,} / {effective_weekly:,} tokens ({pct:.1f}%)\n"
-                    f"Edit TOKEN_QUOTA_WEEKLY to change the limit."
-                )
-            }
+            result = {"decision": "block", "reason": (f"Weekly token quota exceeded (rolling 7-day window).\nUsed:  {used_weekly:,} / {effective_weekly:,} tokens ({pct:.1f}%)\nEdit TOKEN_QUOTA_WEEKLY to change the limit.")}
             print(json.dumps(result))
             sys.exit(0)
 
@@ -76,14 +60,7 @@ def main():
         effective_monthly = store.monthly_limit + snooze
         if used_monthly >= effective_monthly:
             pct = (used_monthly / effective_monthly) * 100
-            result = {
-                "decision": "block",
-                "reason": (
-                    f"Monthly token quota exceeded.\n"
-                    f"Used:  {used_monthly:,} / {effective_monthly:,} tokens ({pct:.1f}%)\n"
-                    f"Quota resets on the 1st. Edit TOKEN_QUOTA_MONTHLY to change the limit."
-                )
-            }
+            result = {"decision": "block", "reason": (f"Monthly token quota exceeded.\nUsed:  {used_monthly:,} / {effective_monthly:,} tokens ({pct:.1f}%)\nQuota resets on the 1st. Edit TOKEN_QUOTA_MONTHLY to change the limit.")}
             print(json.dumps(result))
             sys.exit(0)
 

hooks/quota_status.py

@@ -11,10 +11,7 @@
 import json
 import os
 from datetime import date, timedelta
-from pathlib import Path
-import sys
 
-sys.path.insert(0, str(Path(__file__).parent))
 from quota_store import QuotaStore
 
 _cost_raw = os.environ.get("TOKEN_QUOTA_COST_PER_M")
@@ -41,12 +38,12 @@ def main():
 
     if store.monthly_limit is not None and store.retain_days < 31:
         print(f"  ⚠️  WARNING: TOKEN_QUOTA_RETAIN_DAYS={store.retain_days} is below 31.")
-        print(f"  Monthly totals may be incomplete for 31-day months.")
-        print(f"  Set TOKEN_QUOTA_RETAIN_DAYS=31 or higher to fix this.")
+        print("  Monthly totals may be incomplete for 31-day months.")
+        print("  Set TOKEN_QUOTA_RETAIN_DAYS=31 or higher to fix this.")
 
-    print(f"\n{'─'*50}")
+    print(f"\n{'─' * 50}")
     print(f"  Claude Code Token Quota — {today.isoformat()}")
-    print(f"{'─'*50}")
+    print(f"{'─' * 50}")
 
     snooze = store.get_snooze()
 
@@ -106,7 +103,7 @@ def main():
             print(f"  Snooze:    {snooze:>12,} tokens  (expires midnight)")
         print(f"  Status:    {status}")
 
-    print(f"\n{'─'*50}\n")
+    print(f"\n{'─' * 50}\n")
 
 
 if __name__ == "__main__":

hooks/quota_store.py

@@ -2,11 +2,6 @@
 quota_store.py — shared data access layer for all token-quota hooks.
 
 Encapsulates config parsing, ledger reads/writes, snooze state, and cleanup.
-Import via:
-    import sys
-    from pathlib import Path
-    sys.path.insert(0, str(Path(__file__).parent))
-    from quota_store import QuotaStore
 """
 
 import json
@@ -99,7 +94,12 @@ def get_snooze(self) -> int:
     def write_snooze(self, extra_tokens: int):
         self.ledger_dir.mkdir(parents=True, exist_ok=True)
         snooze_file = self.ledger_dir / "snooze.json"
-        snooze_file.write_text(json.dumps({
-            "extra_tokens": extra_tokens,
-            "expires": date.today().isoformat(),
-        }, indent=2))
+        snooze_file.write_text(
+            json.dumps(
+                {
+                    "extra_tokens": extra_tokens,
+                    "expires": date.today().isoformat(),
+                },
+                indent=2,
+            )
+        )

hooks/snooze.py

@@ -6,18 +6,14 @@
 Set TOKEN_QUOTA_SNOOZE_TOKENS to change the snooze amount (default: 1,000,000).
 """
 
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
 from quota_store import QuotaStore
 
 
 def main():
     store = QuotaStore()
     store.write_snooze(store.snooze_tokens)
     print(f"Quota snoozed: +{store.snooze_tokens:,} tokens added to all limits for today.")
-    print(f"Expires at midnight. Set TOKEN_QUOTA_SNOOZE_TOKENS to change the amount.")
+    print("Expires at midnight. Set TOKEN_QUOTA_SNOOZE_TOKENS to change the amount.")
 
 
 if __name__ == "__main__":

hooks/track_tokens.py

@@ -9,7 +9,6 @@
 from datetime import datetime
 from pathlib import Path
 
-sys.path.insert(0, str(Path(__file__).parent))
 from quota_store import QuotaStore
 
 
@@ -49,10 +48,10 @@ def main():
     if not usage:
         sys.exit(0)
 
-    input_tokens  = usage.get("input_tokens", 0)
+    input_tokens = usage.get("input_tokens", 0)
     output_tokens = usage.get("output_tokens", 0)
-    cache_write   = usage.get("cache_creation_input_tokens", 0)
-    cache_read    = usage.get("cache_read_input_tokens", 0)
+    cache_write = usage.get("cache_creation_input_tokens", 0)
+    cache_read = usage.get("cache_read_input_tokens", 0)
     total = input_tokens + output_tokens + cache_write + cache_read
 
     if total == 0:
@@ -61,13 +60,15 @@ def main():
     store = QuotaStore()
     ledger = store.load_ledger()
     ledger["total_tokens"] += total
-    ledger["sessions"].append({
-        "timestamp": datetime.now().isoformat(timespec="seconds"),
-        "input_tokens": input_tokens,
-        "output_tokens": output_tokens,
-        "cache_write_tokens": cache_write,
-        "cache_read_tokens": cache_read,
-    })
+    ledger["sessions"].append(
+        {
+            "timestamp": datetime.now().isoformat(timespec="seconds"),
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "cache_write_tokens": cache_write,
+            "cache_read_tokens": cache_read,
+        }
+    )
     store.save_ledger(ledger)
 
     print(f"[token-quota] +{total:,} tokens this turn | today total: {ledger['total_tokens']:,}", file=sys.stderr)