Enforce stricter linting across the entire codebase, covering both TypeScript and Python files. (#96)

* upgrade-to-eslint-9

* lint-python

* add-eslint.config.mjs

* Automatic application of license header

* lint

* fix-ruff-lints

* more-python-lint-fixes

* Automatic application of license header

* move-comment-up

* more-fixes

* address-feedbacks

* import-types

* lint

* fix-lint

* lint-more-and-enable-mypy

* lint-test-files

* fix-tests

* ignore-semver-file

* revert-semver-file

* add-mypy-ignore-comments

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: Darshan808

.licenserc.yaml

@@ -22,6 +22,7 @@ header:
     - 'yarn.lock'
     - 'jupyter_builder/yarn.js'
     - 'jupyter_builder/_version.py'
+    - 'jupyter_builder/jupyterlab_semver.py'
     - THIRD_PARTY_LICENSES/**
 
   comment: on-failure

.pre-commit-config.yaml

@@ -49,13 +49,12 @@ repos:
       - id: rst-inline-touching-normal
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.8.0"
+    rev: "v1.15.0"
     hooks:
       - id: mypy
-        files: jupyter_server
-        stages: [manual]
+        files: ^jupyter_builder/
         additional_dependencies:
-          ["traitlets>=5.13"]
+          ["traitlets", "jupyter-core", "types-requests"]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.11
@@ -65,9 +64,3 @@ repos:
         args: ["--fix", "--show-fixes"]
       - id: ruff-format
         types_or: [python, jupyter]
-
-  # - repo: https://github.com/scientific-python/cookie
-  #   rev: "2024.01.24"
-  #   hooks:
-  #     - id: sp-repo-review
-  #       additional_dependencies: ["repo-review[cli]"]

eslint.config.mjs

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettierPluginRecommended from 'eslint-plugin-prettier/recommended';
+import { defineConfig, globalIgnores } from 'eslint/config';
+
+export default defineConfig([
+  globalIgnores([
+    'node_modules/',
+    'lib/',
+    'dist/',
+    'coverage/',
+    '**/*.d.ts',
+    'jupyter_builder/yarn.js'
+  ]),
+  {
+    files: ['**/*.ts'],
+    extends: [js.configs.recommended, tseslint.configs.recommended],
+    plugins: {
+      '@typescript-eslint': tseslint.plugin
+    },
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        project: './tsconfig.json'
+      }
+    },
+    rules: {
+      '@typescript-eslint/no-namespace': 'off',
+      '@typescript-eslint/no-require-imports': 'off'
+    }
+  },
+  prettierPluginRecommended
+]);

jupyter_builder/__init__.py

@@ -1,3 +1,5 @@
+"""Jupyter Builder package."""
+
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 

jupyter_builder/base_extension_app.py

@@ -5,16 +5,16 @@
 
 from __future__ import annotations
 
-import os
 from copy import copy
+from pathlib import Path
 
 from jupyter_core.application import JupyterApp, base_aliases, base_flags
 from jupyter_core.paths import jupyter_path
 from traitlets import List, Unicode, default
 
 from .debug_log_file_mixin import DebugLogFileMixin
 
-HERE = os.path.dirname(os.path.abspath(__file__))
+HERE = str(Path(__file__).resolve().parent)
 
 flags = dict(base_flags)
 
@@ -27,11 +27,12 @@
 aliases = dict(base_aliases)
 aliases["debug-log-path"] = "DebugLogFileMixin.debug_log_path"
 
-# VERSION = get_app_version()
-VERSION = 1
+VERSION = "1"
 
 
 class BaseExtensionApp(JupyterApp, DebugLogFileMixin):
+    """Base application class for JupyterLab extension CLI commands."""
+
     version = VERSION
     flags = flags
     aliases = aliases
@@ -42,22 +43,18 @@ class BaseExtensionApp(JupyterApp, DebugLogFileMixin):
         help="The standard paths to look in for prebuilt JupyterLab extensions",
     )
 
-    # @default("labextensions_path")
-    # def _default_labextensions_path(self):
-    # lab = LabApp()
-    # lab.load_config_file()
-    # return lab.extra_labextensions_path + lab.labextensions_path
     @default("labextensions_path")
     def _default_labextensions_path(self) -> list[str]:
         return jupyter_path("labextensions")
 
-    def start(self):
+    def start(self) -> None:
+        """Start the extension app and run the configured task."""
         with self.debug_logging():
             self.run_task()
 
-    def run_task(self):
-        pass
+    def run_task(self) -> None:
+        """Execute the app's primary task; override in subclasses."""
 
-    def _log_format_default(self):
-        """A default format for messages"""
+    def _log_format_default(self) -> str:
+        """Return the default log format string."""
         return "%(message)s"

jupyter_builder/commands.py

@@ -1,28 +1,47 @@
-"""JupyterLab command handler"""
+"""JupyterLab command handler."""
 
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 
+from __future__ import annotations
+
 import itertools
+from collections.abc import Callable
+from typing import Any
 
 from .jupyterlab_semver import Range, gt, gte, lt, lte
 
+_CmpFn = Callable[[str | Any, str | Any, bool], bool]
+
 
-def _test_overlap(spec1, spec2, drop_prerelease1=False, drop_prerelease2=False):
+def _test_overlap(
+    spec1: str,
+    spec2: str,
+    drop_prerelease1: bool = False,
+    drop_prerelease2: bool = False,
+) -> bool | None:
     """Test whether two version specs overlap.
 
     Returns `None` if we cannot determine compatibility,
     otherwise whether there is an overlap
     """
     cmp = _compare_ranges(
-        spec1, spec2, drop_prerelease1=drop_prerelease1, drop_prerelease2=drop_prerelease2
+        spec1,
+        spec2,
+        drop_prerelease1=drop_prerelease1,
+        drop_prerelease2=drop_prerelease2,
     )
     if cmp is None:
-        return
+        return None
     return cmp == 0
 
 
-def _compare_ranges(spec1, spec2, drop_prerelease1=False, drop_prerelease2=False):  # noqa
+def _compare_ranges(  # noqa: C901, PLR0912
+    spec1: str,
+    spec2: str,
+    drop_prerelease1: bool = False,
+    drop_prerelease2: bool = False,
+) -> int | None:
     """Test whether two version specs overlap.
 
     Returns `None` if we cannot determine compatibility,
@@ -31,15 +50,15 @@ def _compare_ranges(spec1, spec2, drop_prerelease1=False, drop_prerelease2=False
     is higher/newer than spec2.
     """
     # Test for overlapping semver ranges.
-    r1 = Range(spec1, True)
-    r2 = Range(spec2, True)
+    r1 = Range(spec1, True)  # type: ignore[no-untyped-call]
+    r2 = Range(spec2, True)  # type: ignore[no-untyped-call]
 
     # If either range is empty, we cannot verify.
     if not r1.range or not r2.range:
-        return
+        return None
 
     # Set return_value to a sentinel value
-    return_value = False
+    return_value: int | bool | None = False
 
     # r1.set may be a list of ranges if the range involved an ||,
     # so we need to test for overlaps between each pair.
@@ -63,13 +82,14 @@ def _compare_ranges(spec1, spec2, drop_prerelease1=False, drop_prerelease2=False
             continue
 
         # Handle single value specifiers.
-        lx = lte if x1 == x2 else lt
-        ly = lte if y1 == y2 else lt
-        gx = gte if x1 == x2 else gt
-        gy = gte if x1 == x2 else gt
+        lx: _CmpFn = lte if x1 == x2 else lt
+        ly: _CmpFn = lte if y1 == y2 else lt
+        gx: _CmpFn = gte if x1 == x2 else gt
+        gy: _CmpFn = gte if x1 == x2 else gt
 
         # Handle unbounded (>) specifiers.
-        def noop(x, y, z):
+        def noop(_x: str | Any, _y: str | Any, _z: bool) -> bool:
+            """Return True unconditionally, representing an unbounded range."""
             return True
 
         if x1 == x2 and o1.startswith(">"):
@@ -79,15 +99,15 @@ def noop(x, y, z):
 
         # Check for overlap.
         if (
-            (gte(x1, y1, True) and ly(x1, y2, True))
+            (gte(x1, y1, True) and ly(x1, y2, True))  # type: ignore[no-untyped-call]
             or (gy(x2, y1, True) and ly(x2, y2, True))
-            or (gte(y1, x1, True) and lx(y1, x2, True))
+            or (gte(y1, x1, True) and lx(y1, x2, True))  # type: ignore[no-untyped-call]
             or (gx(y2, x1, True) and lx(y2, x2, True))
         ):
             # if we ever find an overlap, we can return immediately
             return 0
 
-        if gte(y1, x2, True):
+        if gte(y1, x2, True):  # type: ignore[no-untyped-call]
             if return_value is False:
                 # We can possibly return 1
                 return_value = 1
@@ -96,7 +116,7 @@ def noop(x, y, z):
                 return_value = None
             continue
 
-        if gte(x1, y2, True):
+        if gte(x1, y2, True):  # type: ignore[no-untyped-call]
             if return_value is False:
                 return_value = -1
             elif return_value == 1:

jupyter_builder/core_path.py

@@ -1,3 +1,5 @@
+"""Utilities for locating and resolving JupyterLab core package metadata."""
+
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 
@@ -15,8 +17,10 @@ def _home_dir() -> Path:
 
 
 def get_core_meta(
-    version: str | None = None, ext_path: str | os.PathLike[str] | None = None
+    version: str | None = None,
+    ext_path: str | os.PathLike[str] | None = None,
 ) -> str:
+    """Return the path to the core package JSON, downloading it if needed."""
     requested_version = version
 
     if requested_version is None:
@@ -48,13 +52,12 @@ def get_core_meta(
 
 
 def _is_wildcard_version(version: str) -> bool:
-    """Returns True for npm range-style versions like 4.5.x"""
+    """Return True for npm range-style versions like 4.5.x."""
     return bool(re.search(r"\.x(\.|$)|(^|\.)x\.", version, flags=re.IGNORECASE))
 
 
 def _resolve_npm_version(version: str) -> str:
-    """
-    Resolves an abstract version specifier to a concrete npm version string.
+    """Resolve an abstract version specifier to a concrete npm version string.
 
     - 'latest'  → fetches the current latest tag from npm
     - '4.5.x'   → fetches all published versions and returns the highest 4.5.x match
@@ -76,9 +79,7 @@ def _resolve_npm_version(version: str) -> str:
 
 
 def _resolve_wildcard_npm_version(version: str) -> str:
-    """
-    Given a wildcard range like '4.5.x', fetches all published versions
-    from npm and returns the highest semver match.
+    """Fetch the highest published npm version matching a wildcard range like '4.5.x'.
 
     Raises requests.RequestException if no matching version is found.
     """

jupyter_builder/debug_log_file_mixin.py

@@ -1,3 +1,5 @@
+"""Debug log file context manager mixin for Jupyter applications."""
+
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 
@@ -8,19 +10,24 @@
 import tempfile
 import traceback
 import warnings
+from collections.abc import Iterator
+from pathlib import Path
 
 from traitlets import Unicode
 from traitlets.config import Configurable
 
 
 class DebugLogFileMixin(Configurable):
+    """Mixin that adds a debug log file context manager to Jupyter applications."""
+
     debug_log_path = Unicode("", config=True, help="Path to use for the debug log file")
 
     @contextlib.contextmanager
-    def debug_logging(self):
+    def debug_logging(self) -> Iterator[None]:
+        """Context manager that routes all log output to a debug file."""
         log_path = self.debug_log_path
-        if os.path.isdir(log_path):
-            log_path = os.path.join(log_path, "jupyterlab-debug.log")
+        if Path(log_path).is_dir():
+            log_path = str(Path(log_path) / "jupyterlab-debug.log")
         if not log_path:
             handle, log_path = tempfile.mkstemp(prefix="jupyterlab-debug-", suffix=".log")
             os.close(handle)
@@ -48,7 +55,8 @@ def debug_logging(self):
                 self.log.debug(line)
             if isinstance(ex, SystemExit):
                 warnings.warn(
-                    f"An error occurred. See the log file for details: {log_path}", stacklevel=1
+                    f"An error occurred. See the log file for details: {log_path}",
+                    stacklevel=1,
                 )
                 raise
             warnings.warn("An error occurred.", stacklevel=1)
@@ -60,5 +68,5 @@ def debug_logging(self):
             _debug_handler.flush()
             _debug_handler.close()
             with contextlib.suppress(FileNotFoundError):
-                os.remove(log_path)
+                Path(log_path).unlink()
         log.removeHandler(_debug_handler)

jupyter_builder/extension_commands/__init__.py

@@ -1,2 +1,4 @@
+"""Extension command entry points for JupyterLab builder."""
+
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.