Rename file language helper function (#3661)

## Changes
Rename and document getting supported file language helper function to
make more clear what it does.

IMO it was not clear that this function contains essential decision
power as it is the filter for passing files to the linter only if they
are supported (in contrast with inferring any language - also the
non-supported ones).

For example, before #3655, the `FileLinter` contains filters for
extensions, however this redundant as that is already handled by this
helper function.

The rename makes it more explicit what this function does. The
documentation makes it more clear how to use the function

### Functionality

- [x] modified linter related code.

Author: JCZuurmond

src/databricks/labs/ucx/source_code/base.py

@@ -320,7 +320,14 @@ def parse_security_mode(mode_str: str | None) -> compute.DataSecurityMode | None
 }
 
 
-def file_language(path: Path) -> Language | None:
+def infer_file_language_if_supported(path: Path) -> Language | None:
+    """Infer the file language if it is supported by UCX's linter module.
+
+    This function returns the language of the file based on the file
+    extension. If the file extension is not supported, it returns None.
+
+    Use this function to filter paths before passing it to the linters.
+    """
     return SUPPORTED_EXTENSION_LANGUAGES.get(path.suffix.lower())
 
 
@@ -415,7 +422,7 @@ def is_a_notebook(path: Path, content: str | None = None) -> bool:
         return path.is_notebook()
     if not path.is_file():
         return False
-    language = file_language(path)
+    language = infer_file_language_if_supported(path)
     if not language:
         return False
     magic_header = f"{LANGUAGE_COMMENT_PREFIXES.get(language)} {NOTEBOOK_HEADER}"

src/databricks/labs/ucx/source_code/files.py

@@ -6,7 +6,7 @@
 
 from databricks.sdk.service.workspace import Language
 
-from databricks.labs.ucx.source_code.base import file_language, safe_read_text
+from databricks.labs.ucx.source_code.base import infer_file_language_if_supported, safe_read_text
 from databricks.labs.ucx.source_code.graph import (
     SourceContainer,
     DependencyGraph,
@@ -95,7 +95,7 @@ def load_dependency(self, path_lookup: PathLookup, dependency: Dependency) -> Lo
             # Paths are excluded from further processing by loading them as stub container.
             # Note we don't return `None`, as the path is found.
             return StubContainer(resolved_path)
-        language = file_language(resolved_path)
+        language = infer_file_language_if_supported(resolved_path)
         if not language:
             return StubContainer(resolved_path)
         content = safe_read_text(resolved_path)

src/databricks/labs/ucx/source_code/linters/files.py

@@ -9,9 +9,9 @@
 from databricks.sdk.service.workspace import Language
 
 from databricks.labs.ucx.source_code.base import (
-    file_language,
     Advice,
     Failure,
+    infer_file_language_if_supported,
     safe_read_text,
 )
 from databricks.labs.ucx.source_code.files import LocalFile
@@ -201,9 +201,9 @@ def _resolve_and_parse_notebook_path(self, path: Path | None) -> Notebook | None
         if resolved is None:
             return None  # already reported during dependency building
         # TODO deal with workspace notebooks
-        language = file_language(resolved)
+        language = infer_file_language_if_supported(resolved)
         # we only support Python notebooks for now
-        if language is not Language.PYTHON:
+        if language != Language.PYTHON:
             logger.warning(f"Unsupported notebook language: {language}")
             return None
         source = safe_read_text(resolved)

src/databricks/labs/ucx/source_code/linters/graph_walkers.py

@@ -18,7 +18,7 @@
     LocatedAdvice,
     UsedTable,
     SourceInfo,
-    file_language,
+    infer_file_language_if_supported,
     is_a_notebook,
     safe_read_text,
 )
@@ -149,9 +149,9 @@ def _process_dependency(
         path_lookup: PathLookup,
         inherited_tree: Tree | None,
     ) -> Iterable[S]:
-        language = file_language(dependency.path)
+        language = infer_file_language_if_supported(dependency.path)
         if not language:
-            logger.warning(f"Unknown language for {dependency.path}")
+            logger.warning(f"Unsupported language for {dependency.path}")
             return
         cell_language = CellLanguage.of_language(language)
         source = safe_read_text(dependency.path)

src/databricks/labs/ucx/source_code/notebooks/loaders.py

@@ -6,7 +6,7 @@
 
 from databricks.sdk.service.workspace import Language
 
-from databricks.labs.ucx.source_code.base import is_a_notebook, file_language, safe_read_text
+from databricks.labs.ucx.source_code.base import infer_file_language_if_supported, is_a_notebook, safe_read_text
 from databricks.labs.ucx.source_code.graph import (
     BaseNotebookResolver,
     Dependency,
@@ -102,7 +102,7 @@ def load_dependency(self, path_lookup: PathLookup, dependency: Dependency) -> No
 
     @staticmethod
     def _detect_language(path: Path, content: str) -> Language | None:
-        language = file_language(path)
+        language = infer_file_language_if_supported(path)
         if language:
             return language
         for cell_language in CellLanguage: