Create an API for linting a file by path (#4163)

* Create an API for linting a file by path

Author: kddejong

src/cfnlint/__init__.py

@@ -5,7 +5,7 @@
 
 import logging
 
-from cfnlint.api import lint, lint_all
+from cfnlint.api import lint, lint_all, lint_file
 from cfnlint.config import ConfigMixIn, ManualArgs
 from cfnlint.rules import Rules
 from cfnlint.template import Template

src/cfnlint/api.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+from pathlib import Path
 from typing import List
 
 from cfnlint.config import ConfigMixIn, ManualArgs
@@ -82,3 +83,42 @@ def lint_all(s: str) -> list[Match]:
             include_checks=["I"], include_experimental=True, regions=REGIONS
         ),
     )
+
+
+def lint_file(
+    template: Path,
+    config: ManualArgs | None = None,
+) -> list[Match]:
+    """Validate a template file using the configuration provided.
+
+    Parameters
+    ----------
+    filename : str
+        Path to the CloudFormation template file
+    config : ManualArgs
+        Configuration options for the linter
+
+    Returns
+    -------
+    list
+        a list of errors if any were found, else an empty list
+    """
+
+    if not template.exists():
+        from cfnlint.rules.errors import ParseError
+
+        return [
+            Match.create(
+                filename=str(template),
+                rule=ParseError(),
+                message=f"Template file not found: {str(template)}",
+            )
+        ]
+
+    if not config:
+        config_mixin = ConfigMixIn(["--template", str(template)])
+    else:
+        config_mixin = ConfigMixIn(["--template", str(template)], **config)
+
+    runner = Runner(config_mixin)
+    return list(runner.run())

test/unit/module/test_api.py

@@ -5,9 +5,12 @@
 
 from __future__ import annotations
 
+import os
+import tempfile
+from pathlib import Path
 from unittest import TestCase
 
-from cfnlint import lint, lint_all
+from cfnlint import lint, lint_all, lint_file
 from cfnlint.config import ManualArgs
 from cfnlint.core import get_rules
 from cfnlint.helpers import REGIONS
@@ -167,3 +170,113 @@ def test_sam_template(self):
         filename = "test/fixtures/templates/good/transform/list_transform_many.yaml"
         matches = self.helper_lint_string_from_file(filename)
         self.assertEqual([], matches, f"Got matches: {matches!r}")
+
+
+class TestLintFile(TestCase):
+    """Test the lint_file API function"""
+
+    def test_nonexistent_file(self):
+        """Test linting a file that doesn't exist"""
+        matches = lint_file(Path("nonexistent_file.yaml"))
+        self.assertEqual(1, len(matches))
+        self.assertEqual("E0000", matches[0].rule.id)
+        self.assertIn("Template file not found", matches[0].message)
+
+    def test_noecho_yaml_template(self):
+        """Test linting a template with NoEcho issues"""
+        filename = Path("test/fixtures/templates/bad/noecho.yaml")
+        matches = lint_file(
+            filename,
+            config=ManualArgs(regions=["us-east-1", "us-west-2", "eu-west-1"]),
+        )
+        self.assertEqual(
+            ["W2010", "W2010"],
+            [match.rule.id for match in matches],
+            f"Got matches: {matches!r}",
+        )
+
+    def test_noecho_yaml_template_warnings_ignored(self):
+        """Test linting with warnings ignored"""
+        filename = Path("test/fixtures/templates/bad/noecho.yaml")
+        matches = lint_file(
+            filename,
+            config=ManualArgs(
+                ignore_checks=["W", "I"],
+            ),
+        )
+        self.assertListEqual([], matches, f"Got matches: {matches!r}")
+
+    def test_duplicate_json_template(self):
+        """Test linting a template with duplicate keys"""
+        filename = Path("test/fixtures/templates/bad/duplicate.json")
+        matches = lint_file(
+            filename,
+            config=ManualArgs(
+                regions=["us-east-1", "us-west-2", "eu-west-1"],
+            ),
+        )
+        self.assertEqual(
+            ["E0000", "E0000", "E0000"],
+            [match.rule.id for match in matches],
+            f"Got matches: {matches!r}",
+        )
+
+    def test_invalid_yaml_template(self):
+        """Test linting an invalid YAML template"""
+        filename = Path("test/fixtures/templates/bad/core/config_invalid_yaml.yaml")
+        matches = lint_file(
+            filename,
+            config=ManualArgs(regions=["us-east-1", "us-west-2", "eu-west-1"]),
+        )
+        self.assertEqual(
+            ["E0000"], [match.rule.id for match in matches], f"Got matches: {matches!r}"
+        )
+
+    def test_invalid_json_template(self):
+        """Test linting an invalid JSON template"""
+        filename = Path("test/fixtures/templates/bad/core/config_invalid_json.json")
+        matches = lint_file(
+            filename,
+            config=ManualArgs(regions=["us-east-1", "us-west-2", "eu-west-1"]),
+        )
+        self.assertEqual(
+            ["E0000"], [match.rule.id for match in matches], f"Got matches: {matches!r}"
+        )
+
+    def test_issues_template(self):
+        """Test linting a template with issues"""
+        filename = Path("test/fixtures/templates/bad/issues.yaml")
+        matches = lint_file(
+            filename,
+            config=ManualArgs(regions=["us-east-1", "us-west-2", "eu-west-1"]),
+        )
+        self.assertEqual(
+            ["E1020"], [match.rule.id for match in matches], f"Got matches: {matches!r}"
+        )
+
+    def test_sam_template(self):
+        """Test linting a SAM template"""
+        filename = Path(
+            "test/fixtures/templates/good/transform/list_transform_many.yaml"
+        )
+        matches = lint_file(filename)
+        self.assertEqual([], matches, f"Got matches: {matches!r}")
+
+    def test_empty_file(self):
+        """Test linting an empty file"""
+        with tempfile.NamedTemporaryFile(delete=False) as temp_file:
+            temp_file.write(b"")
+            temp_file_path = Path(temp_file.name)
+
+        try:
+            matches = lint_file(temp_file_path)
+            self.assertEqual(1, len(matches))
+            self.assertEqual("E1001", matches[0].rule.id)
+        finally:
+            os.unlink(temp_file_path)
+
+    def test_good_template(self):
+        """Test linting a good template"""
+        filename = Path("test/fixtures/templates/good/generic.yaml")
+        matches = lint_file(filename)
+        self.assertEqual([], matches, f"Got matches: {matches!r}")