refactor: improve subprocess error handling and enhance linting script documentation

bin/actions/lint.py

@@ -45,7 +45,7 @@ def lint_ansible(fix=False):
         command.append("--fix")
     command.extend(files_to_lint)
 
-    result = subprocess.run(command)
+    result = subprocess.run(command, check=False)
     return result.returncode
 
 
@@ -68,7 +68,7 @@ def lint_nix():
     exit_code = 0
     for nix_file in nix_files:
         printfe("cyan", f"Formatting {nix_file}")
-        result = subprocess.run(["nixfmt", str(nix_file)])
+        result = subprocess.run(["nixfmt", str(nix_file)], check=False)
         if result.returncode != 0:
             exit_code = 1
 
@@ -89,7 +89,7 @@ def lint_python(fix=False):
     if command_exists("pylint"):
         printfe("blue", "Running pylint...")
         files_to_lint = [str(f) for f in python_files]
-        result = subprocess.run(["pylint"] + files_to_lint)
+        result = subprocess.run(["pylint"] + files_to_lint, check=False)
         if result.returncode != 0:
             exit_code = 1
     else:
@@ -105,7 +105,7 @@ def lint_python(fix=False):
             black_args.append("--check")
         black_args.extend([str(f) for f in python_files])
 
-        result = subprocess.run(black_args)
+        result = subprocess.run(black_args, check=False)
         if result.returncode != 0:
             exit_code = 1
     else:
@@ -114,7 +114,7 @@ def lint_python(fix=False):
     if not command_exists("pylint") and not command_exists("black"):
         printfe(
             "red",
-            "Neither pylint nor black is installed. Install them with pip: pip install pylint black",
+            "Neither pylint nor black is installed. Please run: `pip install pylint black`",
         )
         return 1
 
@@ -122,6 +122,23 @@ def lint_python(fix=False):
 
 
 def main():
+    """
+    Entry point for running linters on dotfiles.
+
+    This function parses command-line arguments to determine which linters to run
+    and whether to apply auto-fixes. It supports running linters for Ansible, Nix,
+    and Python files. If no specific linter is specified, all linters are executed.
+
+    Command-line arguments:
+        --ansible: Run only ansible-lint.
+        --nix: Run only nixfmt.
+        --python: Run only Python linters (pylint, black).
+        --fix: Auto-fix issues where possible.
+
+    Returns:
+        int: Exit code indicating the success or failure of the linting process.
+             A non-zero value indicates that one or more linters reported issues.
+    """
     parser = argparse.ArgumentParser(description="Run linters on dotfiles")
     parser.add_argument("--ansible", action="store_true", help="Run only ansible-lint")
     parser.add_argument("--nix", action="store_true", help="Run only nixfmt")

bin/helpers/functions.py

@@ -143,7 +143,7 @@ def ensure_dependencies():
     if not success:
         printfe(
             "red",
-            "Pip is required to install missing dependencies, try again after running `dotf update`",
+            "Pip is required to install missing dependencies, retry after running `dotf update`",
         )
         return False