feat: Add --extra-lint-rules option for flexible linting rules support

shashax42 · shashax42 · commit dbdff6046763 · 2025-04-15T01:38:46.000+09:00
- Mark existing --serverless-rules option as deprecated
- Add more flexible --extra-lint-rules option
- Implement support for comma-separated multiple rule modules
- Design to work regardless of installation environment
- Update documentation and schema accordingly
diff --git a/docs/extra-lint-rules.md b/docs/extra-lint-rules.md
@@ -0,0 +1,55 @@
+# SAM CLI 추가 Lint 규칙 사용 가이드
+
+AWS SAM CLI의 `validate` 명령어는 템플릿 검증을 위해 [cfn-lint](https://github.com/aws-cloudformation/cfn-lint)를 사용합니다. 
+이제 SAM CLI는 `--extra-lint-rules` 옵션을 통해 추가 lint 규칙을 지원합니다.
+
+## 사용 방법
+
+```bash
+sam validate --lint --extra-lint-rules="cfn_lint_serverless.rules"
+```
+
+## 인스톨러로 SAM CLI 설치 시 고려사항
+
+SAM CLI를 인스톨러(설치 프로그램)로 설치한 경우, SAM CLI는 자체 Python 환경을 사용합니다. 이 경우 추가 규칙 모듈이 해당 환경에 설치되어 있어야 합니다. 이 때 두 가지 접근 방식이 있습니다:
+
+1. **인스톨러 Python 환경에 패키지 설치**: 인스톨러의 Python 환경에 필요한 패키지를 설치합니다.
+2. **모듈 경로를 전체 경로로 지정**: 사용자 환경에 설치된 패키지의 전체 경로를 지정합니다.
+
+## 사용 예제
+
+### 서버리스 규칙 사용 (cfn-lint-serverless)
+
+```bash
+# 먼저 패키지 설치
+pip install cfn-lint-serverless
+
+# SAM 템플릿 검증 실행
+sam validate --lint --extra-lint-rules="cfn_lint_serverless.rules"
+```
+
+### 여러 규칙 모듈 사용
+
+#### 방법 1: 콤마(,)로 구분하여 지정
+
+여러 규칙 모듈을 콤마(,)로 구분하여 한 번의 옵션으로 지정할 수 있습니다:
+
+```bash
+sam validate --lint --extra-lint-rules="module1.rules,module2.rules,module3.rules"
+```
+
+각 모듈은 자동으로 분리되어 cfn-lint에 전달됩니다.
+
+#### 방법 2: 옵션을 여러 번 사용
+
+`--extra-lint-rules` 옵션을 여러 번 사용하여 여러 규칙 모듈을 지정할 수도 있습니다:
+
+```bash
+sam validate --lint --extra-lint-rules="module1.rules" --extra-lint-rules="module2.rules"
+```
+
+## 참고사항
+
+* 과거에 사용하던 `--serverless-rules` 옵션은 deprecated 되었습니다. 
+* 새로운 `--extra-lint-rules` 옵션을 사용하는 것이 좋습니다.
+* 인스톨러로 SAM CLI를 설치한 경우 추가 규칙이 작동하지 않으면 인스톨러의 Python 환경에 패키지가 설치되어 있는지 확인하세요.
diff --git a/samcli/commands/validate/validate.py b/samcli/commands/validate/validate.py
@@ -60,24 +60,40 @@ class SamTemplate:
 @click.option(
     "--serverless-rules",
     is_flag=True,
-    help="Enable Serverless Rules for linting validation. "
+    help="[DEPRECATED] Enable Serverless Rules for linting validation. "
     "Requires the cfn-lint-serverless package to be installed. "
+    "Use --extra-lint-rules=\"cfn_lint_serverless.rules\" instead. "
     "For more information, see: https://github.com/awslabs/serverless-rules",
 )
+@click.option(
+    "--extra-lint-rules",
+    help="Specify additional lint rules to be used with cfn-lint. "
+         "Format: module.path (e.g. 'cfn_lint_serverless.rules')",
+    default=None
+)
 @save_params_option
 @pass_context
 @track_command
 @check_newer_version
 @print_cmdline_args
 @unsupported_command_cdk(alternative_command="cdk doctor")
 @command_exception_handler
-def cli(ctx, template_file, config_file, config_env, lint, save_params, serverless_rules):
+def cli(ctx, template_file, config_file, config_env, lint, save_params, serverless_rules, extra_lint_rules):
     # All logic must be implemented in the ``do_cli`` method. This helps with easy unit testing
 
-    do_cli(ctx, template_file, lint, serverless_rules)  # pragma: no cover
+    # serverless_rules 옵션이 사용되면 경고 표시 및 extra_lint_rules로 변환
+    if serverless_rules and not extra_lint_rules:
+        click.secho(
+            "Warning: --serverless-rules is deprecated. Please use --extra-lint-rules=\"cfn_lint_serverless.rules\" instead.",
+            fg="yellow"
+        )
+        # 이전 옵션을 새 옵션으로 변환
+        extra_lint_rules = "cfn_lint_serverless.rules"
+
+    do_cli(ctx, template_file, lint, serverless_rules, extra_lint_rules)  # pragma: no cover
 
 
-def do_cli(ctx, template, lint, serverless_rules):
+def do_cli(ctx, template, lint, serverless_rules, extra_lint_rules=None):
     """
     Implementation of the ``cli`` method, just separated out for unit testing purposes
     """
@@ -91,7 +107,7 @@ def do_cli(ctx, template, lint, serverless_rules):
     sam_template = _read_sam_file(template)
 
     if lint:
-        _lint(ctx, sam_template.serialized, template, serverless_rules)
+        _lint(ctx, sam_template.serialized, template, serverless_rules, extra_lint_rules)
     else:
         iam_client = boto3.client("iam")
         validator = SamTemplateValidator(
@@ -143,7 +159,7 @@ def _read_sam_file(template) -> SamTemplate:
     return SamTemplate(serialized=template_string, deserialized=sam_template)
 
 
-def _lint(ctx: Context, template: str, template_path: str, serverless_rules: bool) -> None:
+def _lint(ctx: Context, template: str, template_path: str, serverless_rules: bool = False, extra_lint_rules: str = None) -> None:
     """
     Parses provided SAM template and maps errors from CloudFormation template back to SAM template.
 
@@ -166,6 +182,10 @@ def _lint(ctx: Context, template: str, template_path: str, serverless_rules: boo
 
     from cfnlint.api import ManualArgs, lint
     from cfnlint.runner import InvalidRegionException
+    from samcli.lib.telemetry.event import EventTracker
+
+    # 디버그 정보 추가
+    print(f"디버그 정보: serverless_rules 옵션 값 = {serverless_rules}")
 
     cfn_lint_logger = logging.getLogger(CNT_LINT_LOGGER_NAME)
     cfn_lint_logger.propagate = False
@@ -179,29 +199,44 @@ def _lint(ctx: Context, template: str, template_path: str, serverless_rules: boo
         cfn_lint_logger.propagate = True
         cfn_lint_logger.setLevel(logging.DEBUG)
 
-    # Add Serverless Rules if enabled
+    print(f"디버그 정보: linter_config 초기값 = {linter_config}")
+
+    # 두 옵션을 함께 처리하기 위한 변수 초기화
+    rules_to_append = []
+    
+    # 이전 serverless_rules 옵션 지원 (deprecated)
     if serverless_rules:
-        try:
-            # Track usage of Serverless Rules
-            EventTracker.track_event("UsedFeature", "ServerlessRules")
+        print("디버그 정보: serverless_rules 옵션이 활성화되었습니다.")
+        # Track usage of Serverless Rules
+        EventTracker.track_event("UsedFeature", "ServerlessRules")
+        
+        # Check if cfn-lint-serverless is installed
+        import importlib.util
+        serverless_spec = importlib.util.find_spec("cfn_lint_serverless")
+        print(f"디버그 정보: cfn_lint_serverless 패키지 설치 여부 = {serverless_spec is not None}")
+        
+        if serverless_spec is None:
+            print("디버그 정보: cfn_lint_serverless 패키지가 설치되어 있지 않습니다.")
+            click.secho(
+                "Serverless Rules package (cfn-lint-serverless) is not installed. "
+                "Please install it using: pip install cfn-lint-serverless",
+                fg="red",
+            )
+            raise UserException(
+                "Serverless Rules package (cfn-lint-serverless) is not installed. "
+                "Please install it using: pip install cfn-lint-serverless"
+            )
             
-            # Check if cfn-lint-serverless is installed
-            import importlib.util
-            if importlib.util.find_spec("cfn_lint_serverless") is None:
-                click.secho(
-                    "Serverless Rules package (cfn-lint-serverless) is not installed. "
-                    "Please install it using: pip install cfn-lint-serverless",
-                    fg="red",
-                )
-                raise UserException(
-                    "Serverless Rules package (cfn-lint-serverless) is not installed. "
-                    "Please install it using: pip install cfn-lint-serverless"
-                )
+        try:
+            # Try to import the package
+            import cfn_lint_serverless
+            print("디버그 정보: cfn_lint_serverless 패키지 임포트 성공")
             
-            # Add Serverless Rules to the linter config
-            linter_config["append_rules"] = ["cfn_lint_serverless.rules"]
+            # Serverless Rules를 규칙 목록에 추가
+            rules_to_append.append("cfn_lint_serverless.rules")
             click.secho("Serverless Rules enabled for linting", fg="green")
-        except ImportError:
+        except ImportError as e:
+            print(f"디버그 정보: cfn_lint_serverless 임포트 오류 = {e}")
             click.secho(
                 "Serverless Rules package (cfn-lint-serverless) is not installed. "
                 "Please install it using: pip install cfn-lint-serverless",
@@ -211,21 +246,50 @@ def _lint(ctx: Context, template: str, template_path: str, serverless_rules: boo
                 "Serverless Rules package (cfn-lint-serverless) is not installed. "
                 "Please install it using: pip install cfn-lint-serverless"
             )
+    
+    # 새로운 extra_lint_rules 옵션 지원
+    if extra_lint_rules:
+        print(f"디버그 정보: extra_lint_rules 옵션이 활성화되었습니다. 값: {extra_lint_rules}")
+        # Track usage of Extra Lint Rules
+        EventTracker.track_event("UsedFeature", "ExtraLintRules")
+        
+        # 콤마로 구분된 여러 규칙 모듈을 파싱
+        modules = [module.strip() for module in extra_lint_rules.split(',') if module.strip()]
+        print(f"디버그 정보: 파싱된 규칙 모듈 목록 = {modules}")
+        
+        # 각 모듈을 규칙 목록에 추가
+        rules_to_append.extend(modules)
+        click.secho(f"Extra lint rules enabled: {extra_lint_rules}", fg="green")
+    
+    # 규칙이 있으면 linter_config에 추가
+    if rules_to_append:
+        print(f"디버그 정보: 추가할 규칙 목록 = {rules_to_append}")
+        linter_config["append_rules"] = rules_to_append
+        print(f"디버그 정보: linter_config 업데이트 = {linter_config}")
 
     config = ManualArgs(**linter_config)
+    print(f"디버그 정보: config 생성 완료")
 
     try:
+        print(f"디버그 정보: lint 함수 호출 시작")
         matches = lint(template, config=config)
+        print(f"디버그 정보: lint 함수 호출 완료, matches = {matches}")
     except InvalidRegionException as ex:
+        print(f"디버그 정보: InvalidRegionException 발생 = {ex}")
         raise UserException(
             f"AWS Region was not found. Please configure your region through the --region option.\n{ex}",
             wrapped_from=ex.__class__.__name__,
         ) from ex
+    except Exception as e:
+        print(f"디버그 정보: 예외 발생 = {e}")
+        raise
 
     if not matches:
+        print(f"디버그 정보: 템플릿 검증 성공")
         click.secho("{} is a valid SAM Template".format(template_path), fg="green")
         return
 
+    print(f"디버그 정보: 템플릿 검증 실패, matches = {matches}")
     click.secho(matches)
 
     raise LinterRuleMatchedException("Linting failed. At least one linting rule was matched to the provided template.")
diff --git a/schema/samcli.json b/schema/samcli.json
@@ -196,7 +196,7 @@
           "properties": {
             "parameters": {
               "title": "Parameters for the validate command",
-              "description": "Available parameters for the validate command:\n* template_file:\nAWS SAM template file.\n* profile:\nSelect a specific profile from your credential file to get AWS credentials.\n* region:\nSet the AWS Region of the service. (e.g. us-east-1)\n* beta_features:\nEnable/Disable beta features.\n* debug:\nTurn on debug logging to print debug message generated by AWS SAM CLI and display timestamps.\n* lint:\nRun linting validation on template through cfn-lint. Create a cfnlintrc config file to specify additional parameters. For more information, see: https://github.com/aws-cloudformation/cfn-lint\n* serverless_rules:\nEnable Serverless Rules for linting validation. Requires the cfn-lint-serverless package to be installed. For more information, see: https://github.com/awslabs/serverless-rules\n* save_params:\nSave the parameters provided via the command line to the configuration file.",
+              "description": "Available parameters for the validate command:\n* template_file:\nAWS SAM template file.\n* profile:\nSelect a specific profile from your credential file to get AWS credentials.\n* region:\nSet the AWS Region of the service. (e.g. us-east-1)\n* beta_features:\nEnable/Disable beta features.\n* debug:\nTurn on debug logging to print debug message generated by AWS SAM CLI and display timestamps.\n* lint:\nRun linting validation on template through cfn-lint. Create a cfnlintrc config file to specify additional parameters. For more information, see: https://github.com/aws-cloudformation/cfn-lint\n* serverless_rules:\n[DEPRECATED] Enable Serverless Rules for linting validation. Use --extra-lint-rules=\"cfn_lint_serverless.rules\" instead. Requires the cfn-lint-serverless package to be installed. For more information, see: https://github.com/awslabs/serverless-rules\n* extra_lint_rules:\nSpecify additional lint rules to be used with cfn-lint. Format: module.path (e.g. 'cfn_lint_serverless.rules')\n* save_params:\nSave the parameters provided via the command line to the configuration file.",
               "type": "object",
               "properties": {
                 "template_file": {
@@ -233,7 +233,12 @@
                 "serverless_rules": {
                   "title": "serverless_rules",
                   "type": "boolean",
-                  "description": "Enable Serverless Rules for linting validation. Requires the cfn-lint-serverless package to be installed. For more information, see: https://github.com/awslabs/serverless-rules"
+                  "description": "[DEPRECATED] Enable Serverless Rules for linting validation. Use --extra-lint-rules=\"cfn_lint_serverless.rules\" instead. Requires the cfn-lint-serverless package to be installed. For more information, see: https://github.com/awslabs/serverless-rules"
+                },
+                "extra_lint_rules": {
+                  "title": "extra_lint_rules",
+                  "type": "string",
+                  "description": "Specify additional lint rules to be used with cfn-lint. Format: module.path (e.g. 'cfn_lint_serverless.rules')"
                 },
                 "save_params": {
                   "title": "save_params",
diff --git a/tests/unit/commands/validate/test_cli.py b/tests/unit/commands/validate/test_cli.py
