@sun-asterisk/sunlint 1.3.39 → 1.3.41

package/skill-assets/sunlint-code-quality/rules/python/C020-no-unused-imports.md

@@ -0,0 +1,28 @@
+---
+title: Do Not Import Unused Modules
+impact: MEDIUM
+impactDescription: improves load time and reduces confusion
+tags: clean-code, performance, quality, python
+---
+
+## Do Not Import Unused Modules
+
+Unused imports increase the noise in the file and can sometimes lead to circular dependency issues or unnecessary memory usage.
+
+**Incorrect:**
+```python
+import os
+import sys  # sys is never used
+from pyspark.sql import functions as F
+
+def my_func():
+    return F.col("id")
+```
+
+**Correct:**
+```python
+from pyspark.sql import functions as F
+
+def my_func():
+    return F.col("id")
+```

package/skill-assets/sunlint-code-quality/rules/python/C022-no-unused-variables.md

@@ -0,0 +1,24 @@
+---
+title: Do Not Leave Unused Variables
+impact: MEDIUM
+impactDescription: reduces noise and potential bugs
+tags: clean-code, quality, python
+---
+
+## Do Not Leave Unused Variables
+
+Variables that are declared but never used indicate unfinished work or bugs.
+
+**Incorrect:**
+```python
+def process(data):
+    result = transform(data)
+    temp_var = 10  # Never used
+    return result
+```
+
+**Correct:**
+```python
+def process(data):
+    return transform(data)
+```

package/skill-assets/sunlint-code-quality/rules/python/C023-no-duplicate-names.md

@@ -0,0 +1,27 @@
+---
+title: No Duplicate Variable Names in Scope
+impact: MEDIUM
+impactDescription: prevents shadowing and logic errors
+tags: naming, clean-code, quality, python
+---
+
+## No Duplicate Variable Names in Scope
+
+Reusing variable names in the same scope (shadowing) makes code hard to read and can lead to unexpected behavior.
+
+**Incorrect:**
+```python
+def filter_data(df):
+    df = df.filter(col("id") > 0)
+    # Reusing 'df' name for a different purpose might be confusing if logic grows
+    df = 10 
+    return df
+```
+
+**Correct:**
+```python
+def filter_data(df):
+    filtered_df = df.filter(col("id") > 0)
+    count = 10
+    return filtered_df
+```

package/skill-assets/sunlint-code-quality/rules/python/C024-centralize-constants.md

@@ -0,0 +1,27 @@
+---
+title: Centralize Constants
+impact: MEDIUM
+impactDescription: improves maintainability and prevents magic strings
+tags: maintenance, quality, python, pyspark
+---
+
+## Centralize Constants
+
+Avoid "magic strings" or numbers scattered across the code. Centralize them in a config or constants file.
+
+**Incorrect:**
+```python
+df = df.filter(col("status") == "ACTIVE") # Magic string
+df.write.save("s3://my-bucket/output")     # Hardcoded path
+```
+
+**Correct:**
+```python
+# constants.py
+ORDER_STATUS_ACTIVE = "ACTIVE"
+OUTPUT_PATH = "s3://my-bucket/output"
+
+# main.py
+df = df.filter(col("status") == ORDER_STATUS_ACTIVE)
+df.write.save(OUTPUT_PATH)
+```

package/skill-assets/sunlint-code-quality/rules/python/C029-catch-log-root-cause.md

@@ -0,0 +1,61 @@
+---
+title: All Catch Blocks Must Log Root Cause
+impact: HIGH
+impactDescription: enables debugging and incident response
+tags: error-handling, logging, debugging, observability, quality, python, pyspark
+---
+
+## All Catch Blocks Must Log Root Cause
+
+Silent failures make debugging impossible. Without proper logging, you cannot trace issues in production. In PySpark, unlogged exceptions in executors can lead to data loss or silent corruption.
+
+**Incorrect (silent or minimal logging):**
+
+```python
+try:
+    process_payment(order)
+except Exception:
+    pass  # Empty except - silent failure!
+
+try:
+    save_user(user)
+except Exception as e:
+    return None  # No logging, no context
+```
+
+**Correct (comprehensive error logging):**
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+try:
+    process_payment(order)
+except Exception as error:
+    logger.error('Payment processing failed', extra={
+        'order_id': order.id,
+        'user_id': order.user_id,
+        'amount': order.amount,
+        'error_msg': str(error),
+        'exc_info': True,  # Capture stack trace
+        'request_id': getattr(context, 'request_id', None)
+    })
+    raise PaymentFailedError('Payment could not be processed') from error
+
+# PySpark Context
+try:
+    df.write.save(path)
+except Exception as error:
+    logger.error(f'Failed to save Spark DataFrame to {path}', exc_info=True)
+    raise SparkProcessError(f"Spark write failed for {path}") from error
+```
+
+**Log context should include:**
+- Error message and stack trace (using `exc_info=True`)
+- Relevant entity IDs (order, user, etc.)
+- Request/correlation ID
+- Input parameters that caused the error
+- Timing information
+
+**Tools:** Static analyzer, Pylint, PR review

package/skill-assets/sunlint-code-quality/rules/python/C030-custom-error-classes.md

@@ -0,0 +1,28 @@
+---
+title: Use Custom Error Classes
+impact: HIGH
+impactDescription: enables specific error handling and better logging
+tags: error-handling, quality, python, pyspark
+---
+
+## Use Custom Error Classes
+
+Custom error classes provide context and allow for granular error handling.
+
+**Incorrect:**
+```python
+def process_spark(df):
+    if df.count() == 0:
+        raise Exception("Empty dataframe")
+```
+
+**Correct:**
+```python
+class EmptyDatasetError(Exception):
+    """Raised when the input Spark DataFrame is empty"""
+    pass
+
+def process_spark(df):
+    if df.count() == 0:
+        raise EmptyDatasetError("Input orders table is empty")
+```

package/skill-assets/sunlint-code-quality/rules/python/C033-separate-data-access.md

@@ -0,0 +1,53 @@
+---
+title: Separate Processing and Data Access Layers
+impact: HIGH
+impactDescription: improves testability and maintainability of business logic
+tags: architecture, data-access, layers, quality, python, pyspark
+---
+
+## Separate Processing and Data Access Layers
+
+Mixing business logic with data storage code (SQL, API calls, file I/O) makes code hard to test and maintain. Separating these layers allows you to test business logic without a database or cluster.
+
+**Incorrect (mixed logic and I/O):**
+
+```python
+def process_orders_and_save(spark, input_path, output_path):
+    # Data Access + Logic mixed
+    df = spark.read.parquet(input_path)
+    
+    # Business logic
+    df = df.filter(col("amount") > 100)
+    df = df.withColumn("tax", col("amount") * 0.1)
+    
+    # Data Access mixed
+    df.write.mode("overwrite").parquet(output_path)
+```
+
+**Correct (separated layers):**
+
+```python
+# Processing Layer (Business Logic - Pure Spark transformations)
+def calculate_tax(df):
+    """Business logic that is easy to unit test with mock data"""
+    return df.filter(col("amount") > 100) \
+             .withColumn("tax", col("amount") * 0.1)
+
+# Task/Service Layer (Orchestration)
+def run_order_job(spark, config):
+    # Data Access: Read
+    raw_df = spark.read.parquet(config['input_path'])
+    
+    # Logic: Transform
+    processed_df = calculate_tax(raw_df)
+    
+    # Data Access: Write
+    processed_df.write.mode("overwrite").parquet(config['output_path'])
+```
+
+**Benefits:**
+- **Unit Testability**: You can test `calculate_tax` with small, local DataFrames.
+- **Flexibility**: You can change storage (Parquet to Delta) without touching business logic.
+- **Readability**: The purpose of each function is clear.
+
+**Tools:** Static analyzer, PR review

package/skill-assets/sunlint-code-quality/rules/python/C035-error-context-logging.md

@@ -0,0 +1,26 @@
+---
+title: Log All Relevant Context on Errors
+impact: HIGH
+impactDescription: speeds up troubleshooting
+tags: logging, troubleshooting, quality, python
+---
+
+## Log All Relevant Context on Errors
+
+When an error occurs, log the metadata (IDs, parameters) needed to reproduce it.
+
+**Incorrect:**
+```python
+except Exception as e:
+    logger.error("Upload failed")
+```
+
+**Correct:**
+```python
+except Exception as e:
+    logger.error(f"Upload failed for user {user_id}", extra={
+        "file_id": file_id,
+        "bucket": bucket_name,
+        "exc_info": True
+    })
+```

package/skill-assets/sunlint-code-quality/rules/python/C041-no-hardcoded-secrets.md

@@ -0,0 +1,23 @@
+---
+title: No Hardcoded Secrets in Repo
+impact: CRITICAL
+impactDescription: prevents compromise of credentials
+tags: security, secrets, python
+---
+
+## No Hardcoded Secrets in Repo
+
+Never commit API keys, passwords, or tokens to version control.
+
+**Incorrect:**
+```python
+AWS_SECRET = "AKIA-SECRET-KEY-123"
+db_pass = "admin123"
+```
+
+**Correct:**
+```python
+import os
+AWS_SECRET = os.environ.get("AWS_SECRET_KEY")
+# Or use a secrets manager
+```

package/skill-assets/sunlint-code-quality/rules/python/C042-boolean-naming.md

@@ -0,0 +1,24 @@
+---
+title: Boolean Names: is/has/should Prefix
+impact: MEDIUM
+impactDescription: clarifies variable type and intent
+tags: naming, booleans, quality, python
+---
+
+## Boolean Names: is/has/should Prefix
+
+Boolean variables should be named as questions that yield a yes/no answer.
+
+**Incorrect:**
+```python
+valid = True
+active = False
+login = True
+```
+
+**Correct:**
+```python
+is_valid = True
+has_access = False
+should_login = True
+```

package/skill-assets/sunlint-code-quality/rules/python/C052-controller-parsing.md

@@ -0,0 +1,34 @@
+---
+title: Separate Parsing from Controllers
+impact: MEDIUM
+impactDescription: improves clarity and reuse of logic
+tags: architecture, controller, quality, python
+---
+
+## Separate Parsing from Controllers
+
+In web apps (Flask/FastAPI), separate input validation/parsing from the main request logic.
+
+**Incorrect:**
+```python
+@app.route('/user')
+def get_user():
+    user_id = request.args.get('id')
+    if not user_id or len(user_id) < 5:
+        return "Invalid ID", 400
+    # ... business logic ...
+```
+
+**Correct:**
+```python
+def parse_user_id(args):
+    user_id = args.get('id')
+    if not user_id or len(user_id) < 5:
+        raise InvalidInputError()
+    return user_id
+
+@app.route('/user')
+def get_user():
+    user_id = parse_user_id(request.args)
+    # ... business logic ...
+```

package/skill-assets/sunlint-code-quality/rules/python/C060-superclass-logic.md

@@ -0,0 +1,26 @@
+---
+title: Do Not Ignore Superclass Logic
+impact: MEDIUM
+impactDescription: prevents breaking parent class behavior
+tags: oop, inheritance, quality, python
+---
+
+## Do Not Ignore Superclass Logic
+
+When overriding methods, usually you should call `super()` to ensure parent logic is executed.
+
+**Incorrect:**
+```python
+class MySparkApp(BaseApp):
+    def initialize(self):
+        # ❌ Forgot super().initialize()
+        self.setup_custom()
+```
+
+**Correct:**
+```python
+class MySparkApp(BaseApp):
+    def initialize(self):
+        super().initialize()
+        self.setup_custom()
+```

package/skill-assets/sunlint-code-quality/rules/python/C067-no-hardcoded-config.md

@@ -0,0 +1,22 @@
+---
+title: No Hardcoded Configuration Values
+impact: MEDIUM
+impactDescription: enables environment-specific deployments
+tags: config, architecture, quality, python, pyspark
+---
+
+## No Hardcoded Configuration Values
+
+Environment-specific values (URLs, paths, flags) should be in config files, not code.
+
+**Incorrect:**
+```python
+endpoint = "https://prod-api.example.com"
+```
+
+**Correct:**
+```python
+import yaml
+config = yaml.safe_load(open("config.yaml"))
+endpoint = config['api_endpoint']
+```

package/skill-assets/sunlint-code-quality/rules/python/S003-open-redirect.md

@@ -0,0 +1,16 @@
+---
+title: URL Redirects Must Be In Allow List
+impact: LOW
+impactDescription: prevents open redirect vulnerabilities
+tags: redirect, url, allow-list, validation, security
+---
+
+## URL Redirects Must Be In Allow List
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S004-no-log-credentials.md

@@ -0,0 +1,16 @@
+---
+title: Do Not Log Credentials Or Tokens
+impact: MEDIUM
+impactDescription: prevents credential exposure in logs
+tags: logging, credentials, tokens, secrets, security
+---
+
+## Do Not Log Credentials Or Tokens
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S005-server-authorization.md

@@ -0,0 +1,16 @@
+---
+title: Enforce Authorization At Trusted Service Layer
+impact: CRITICAL
+impactDescription: prevents client-side authorization bypass
+tags: authorization, server-side, middleware, access-control, security
+---
+
+## Enforce Authorization At Trusted Service Layer
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S006-default-credentials.md

@@ -0,0 +1,16 @@
+---
+title: Do Not Use Default Credentials
+impact: CRITICAL
+impactDescription: prevents trivial compromise via known credentials
+tags: credentials, default, passwords, configuration, security
+---
+
+## Do Not Use Default Credentials
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S007-output-encoding.md

@@ -0,0 +1,16 @@
+---
+title: Output Encoding Before Interpreter Use
+impact: HIGH
+impactDescription: prevents XSS and injection attacks
+tags: xss, encoding, output, html, security
+---
+
+## Output Encoding Before Interpreter Use
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S009-approved-crypto.md

@@ -0,0 +1,16 @@
+---
+title: Use Only Approved Crypto Algorithms
+impact: MEDIUM
+impactDescription: ensures cryptographic strength
+tags: cryptography, algorithms, hashing, encryption, security
+---
+
+## Use Only Approved Crypto Algorithms
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S010-csprng.md

@@ -0,0 +1,16 @@
+---
+title: Use CSPRNG For Security Purposes
+impact: HIGH
+impactDescription: prevents predictable tokens and session hijacking
+tags: random, csprng, tokens, session, cryptography, security
+---
+
+## Use CSPRNG For Security Purposes
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S011-encrypted-client-hello.md

@@ -0,0 +1,16 @@
+---
+title: Enable Encrypted Client Hello (ECH)
+impact: MEDIUM
+impactDescription: protects SNI from eavesdropping
+tags: tls, ech, sni, privacy, security
+---
+
+## Enable Encrypted Client Hello (ECH)
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S012-secrets-management.md

@@ -0,0 +1,16 @@
+---
+title: Use Secrets Management For Backend Secrets
+impact: CRITICAL
+impactDescription: centralizes and secures credential storage
+tags: secrets, vault, credentials, configuration, security
+---
+
+## Use Secrets Management For Backend Secrets
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S013-tls-connections.md

@@ -0,0 +1,16 @@
+---
+title: Always Use TLS For All Connections
+impact: HIGH
+impactDescription: protects data in transit from eavesdropping
+tags: tls, https, encryption, transport, security
+---
+
+## Always Use TLS For All Connections
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S016-no-sensitive-query-string.md

@@ -0,0 +1,16 @@
+---
+title: Do Not Pass Sensitive Data In Query String
+impact: HIGH
+impactDescription: prevents credential leakage in logs and history
+tags: url, query-string, sensitive-data, leakage, security
+---
+
+## Do Not Pass Sensitive Data In Query String
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)

package/skill-assets/sunlint-code-quality/rules/python/S017-parameterized-queries.md

@@ -0,0 +1,51 @@
+---
+title: Always Use Parameterized Queries
+impact: CRITICAL
+impactDescription: prevents SQL and NoSQL injection attacks
+tags: injection, sql, spark-sql, database, parameterized, security, python, pyspark
+---
+
+## Always Use Parameterized Queries
+
+SQL injection is one of the top security vulnerabilities. Direct string concatenation allows attackers to execute arbitrary database commands, steal data, or destroy databases. In PySpark, this often happens when building Spark SQL queries with f-strings.
+
+**Incorrect (string concatenation):**
+
+```python
+# SQL Injection vulnerability in standard SQL
+user_id = request.args.get('id')
+query = f"SELECT * FROM users WHERE id = '{user_id}'"
+cursor.execute(query)
+
+# SQL Injection vulnerability in PySpark SQL
+table_name = "orders"
+status = request.args.get('status')
+# UNFAIR: f-string allows manipulation of the SQL structure
+spark.sql(f"SELECT * FROM {table_name} WHERE status = '{status}'")
+```
+
+**Correct (parameterized queries):**
+
+```python
+# Parameterized query - standard DB-API
+user_id = request.args.get('id')
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+
+# Safe PySpark SQL (Spark 3.4+)
+spark.sql(
+    "SELECT * FROM {table} WHERE status = {status}",
+    args={"table": "orders", "status": status}
+)
+
+# Safe PySpark using DataFrame API (Recommended)
+from pyspark.sql.functions import col
+status = request.args.get('status')
+df = spark.table("orders").filter(col("status") == status)
+```
+
+**Benefits:**
+- Prevents malicious code execution
+- Improves query performance through plan caching
+- Handles type escaping automatically
+
+**Tools:** Bandit (B608), SonarQube, Semgrep

package/skill-assets/sunlint-code-quality/rules/python/S019-email-input-sanitization.md

@@ -0,0 +1,16 @@
+---
+title: Sanitize Input Before Sending Emails
+impact: MEDIUM
+impactDescription: prevents email header injection
+tags: email, injection, sanitization, input-validation, security
+---
+
+## Sanitize Input Before Sending Emails
+
+This rule ensures high quality and security in Python and PySpark applications.
+
+**Implementation Guidance:**
+- Follow standard Python best practices (PEP 8)
+- Use type hints for better clarity
+- For PySpark, prefer DataFrame API over SQL strings where possible
+- Ensure proper resource management (using \`with\` statements)