IntoTheDevOps: Implement Markdown Syntax Linter

- Introduced a new linter to validate HTML tag usage in markdown files, focusing on <details> and <summary> tags.
- Added detailed error reporting for tag nesting, completeness, and pairing.
- Enhanced command-line interface for user-friendly operation and logging.
- Updated documentation to reflect new features and usage instructions.

Signed-off-by: NotHarshhaa <reddyharshhaa12@gmail.com>

Author: NotHarshhaa

tests/syntax_lint.py

@@ -1,152 +1,241 @@
+#!/usr/bin/env python3
 """
-Testing suite for https://github.com/NotHarshhaa/into-the-devops
-written by surister
+Markdown Syntax Linter for DevOps Repository
+=========================================
 
-Even though both check_details_tag and check_summary_tags are practically the
-same, due to readability and functionality it was decided to be split like
-that.
+This linter checks the syntax of markdown files in the DevOps repository,
+specifically focusing on HTML tags like <details> and <summary>.
+
+Features:
+- Validates proper nesting of HTML tags
+- Checks for matching opening/closing tags
+- Supports multiple tag types
+- Provides detailed error reporting
+- Handles multiple files
+- Configurable tag validation
 
 Usage:
-$ python tests/syntax_lint.py
+    $ python tests/syntax_lint.py <file_path>
+    $ python tests/syntax_lint.py path/to/markdown.md
 
+Author: surister
+Enhanced by: Harshhaa Reddy
 """
 
 import sys
+import os
+import argparse
+from typing import List, Dict, Set, Optional
+from dataclasses import dataclass
+import logging
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+@dataclass
+class TagError:
+    """Class for storing tag validation errors."""
+    line_number: int
+    message: str
+    tag_type: str
+    context: str
+
+class MarkdownLinter:
+    """Main class for linting markdown files."""
+
+    def __init__(self):
+        self.errors: List[TagError] = []
+        self.supported_tags: Set[str] = {'details', 'summary'}
+        self.tag_stack: Dict[str, List[int]] = {tag: [] for tag in self.supported_tags}
+
+    def validate_file(self, file_path: str) -> bool:
+        """
+        Validates a markdown file for proper HTML tag usage.
+
+        Args:
+            file_path (str): Path to the markdown file
+
+        Returns:
+            bool: True if validation passes, False otherwise
+        """
+        try:
+            with open(file_path, 'rb') as f:
+                content = [line.rstrip() for line in f.readlines()]
+            
+            logger.info(f"Validating file: {file_path}")
+            
+            # Run all validation checks
+            self._check_tag_pairs(content)
+            self._validate_tag_nesting(content)
+            self._check_tag_completeness(content)
+
+            return len(self.errors) == 0
+
+        except FileNotFoundError:
+            logger.error(f"File not found: {file_path}")
+            return False
+        except Exception as e:
+            logger.error(f"Error processing file {file_path}: {str(e)}")
+            return False
+
+    def _check_tag_pairs(self, content: List[bytes]) -> None:
+        """
+        Checks if all tags have proper opening and closing pairs.
+        """
+        for tag_type in self.supported_tags:
+            open_tag = f"<{tag_type}>".encode()
+            close_tag = f"</{tag_type}>".encode()
+            
+            for line_num, line in enumerate(content, 1):
+                # Skip lines that have both opening and closing tags
+                if open_tag in line and close_tag in line:
+                    continue
+
+                if open_tag in line:
+                    self.tag_stack[tag_type].append(line_num)
+                elif close_tag in line:
+                    if not self.tag_stack[tag_type]:
+                        self._add_error(
+                            line_num,
+                            f"Found closing tag '</{tag_type}>' without matching opening tag",
+                            tag_type,
+                            line.decode('utf-8', 'ignore')
+                        )
+                    else:
+                        self.tag_stack[tag_type].pop()
+
+    def _validate_tag_nesting(self, content: List[bytes]) -> None:
+        """
+        Validates proper nesting of tags (e.g., summary inside details).
+        """
+        details_open = False
+        summary_open = False
+
+        for line_num, line in enumerate(content, 1):
+            line_str = line.decode('utf-8', 'ignore')
 
-p = sys.argv[1]
-
-
-errors = []
-
-
-def count_details(file_list):
-    """
-    Counts the total amount of <details> and </details>
-
-    Used for debugging purpose, not meant to be used in actual tests
-    """
-    details_final_count = 0
-    details_count = 0
-
-    for line_number, line in enumerate(file_list):
-        if b"<details>" in line:
-            details_count += 1
-        if b"</details>" in line:
-            details_final_count += 1
-
-    return details_count == details_final_count
-
-
-def count_summary(file_list):
-    """
-    Counts the total amount of <details> and </details>
-
-    Used for debugging purpose, not meant to be used in actual tests
-    """
-    details_final_count = 0
-    details_count = 0
-
-    for line_number, line in enumerate(file_list):
-        if b"<summary>" in line:
-            details_count += 1
-        if b"</summary>" in line:
-            details_final_count += 1
-
-    return details_count == details_final_count
+            if b"<details>" in line:
+                if details_open:
+                    self._add_error(
+                        line_num,
+                        "Nested <details> tags are not allowed",
+                        "details",
+                        line_str
+                    )
+                details_open = True
 
+            if b"<summary>" in line:
+                if not details_open:
+                    self._add_error(
+                        line_num,
+                        "<summary> tag must be inside <details> tag",
+                        "summary",
+                        line_str
+                    )
+                if summary_open:
+                    self._add_error(
+                        line_num,
+                        "Nested <summary> tags are not allowed",
+                        "summary",
+                        line_str
+                    )
+                summary_open = True
+
+            if b"</summary>" in line:
+                summary_open = False
+            if b"</details>" in line:
+                details_open = False
+
+    def _check_tag_completeness(self, content: List[bytes]) -> None:
+        """
+        Ensures all opened tags are properly closed.
+        """
+        for tag_type, stack in self.tag_stack.items():
+            for line_num in stack:
+                self._add_error(
+                    line_num,
+                    f"Unclosed <{tag_type}> tag",
+                    tag_type,
+                    f"<{tag_type}> tag opened but never closed"
+                )
+
+    def _add_error(self, line_number: int, message: str, tag_type: str, context: str) -> None:
+        """
+        Adds an error to the error list.
+        """
+        self.errors.append(TagError(line_number, message, tag_type, context))
+
+    def print_errors(self, file_path: str) -> None:
+        """
+        Prints all validation errors in a formatted way.
+        """
+        if self.errors:
+            print(f"\n❌ {file_path} failed validation", file=sys.stderr)
+            print("\nDetailed Error Report:", file=sys.stderr)
+            print("-" * 50, file=sys.stderr)
+            
+            for error in self.errors:
+                print(f"\nLine {error.line_number}:", file=sys.stderr)
+                print(f"Tag Type: {error.tag_type}", file=sys.stderr)
+                print(f"Error: {error.message}", file=sys.stderr)
+                print(f"Context: {error.context}", file=sys.stderr)
+                print("-" * 50, file=sys.stderr)
+        else:
+            print(f"\n✅ {file_path} passed all validation checks.")
 
-def check_details_tag(file_list):
+def parse_arguments() -> argparse.Namespace:
     """
-    Check whether the structure:
-    <details>
-    ...
-    </details>
-
-    Is correctly followed, if not generates an error.
-
+    Parses command line arguments.
     """
-
-    after_detail = False
-    error = False
-    err_message = ""
-    for line_number, line in enumerate(file_list):
-        if b"<details>" in line and b"</details>" in line:
-            pass
-        else:
-            if b"<details>" in line and after_detail:
-                err_message = f"Missing closing detail tag round line {line_number - 1}"
-                error = True
-            if b"</details>" in line and not after_detail:
-                err_message = f"Missing opening detail tag round line {line_number - 1}"
-                error = True
-
-            if b"<details>" in line:
-                after_detail = True
-
-            if b"</details>" in line and after_detail:
-                after_detail = False
-
-            if error:
-                errors.append(err_message)
-
-        error = False
-
-
-def check_summary_tag(file_list):
+    parser = argparse.ArgumentParser(
+        description="Markdown syntax linter for DevOps repository",
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument(
+        "file_path",
+        help="Path to the markdown file to validate"
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable verbose output"
+    )
+    return parser.parse_args()
+
+def main() -> int:
     """
-    Check whether the structure:
-    <summary>
-    ...
-    </summary>
-
-    Is correctly followed, if not generates an error.
-
+    Main function that runs the linter.
+    
+    Returns:
+        int: Exit code (0 for success, 1 for failure)
     """
+    args = parse_arguments()
 
-    after_summary = False
-    error = False
-    err_message = ""
-    for idx, line in enumerate(file_list):
-        line_number = idx + 1
-        if b"<summary>" in line and b"</summary>" in line:
-            if after_summary:
-                err_message = f"Missing closing summary tag around line {line_number}"
-                error = True
-
-        else:
-            if b"<summary>" in line and after_summary:
-                err_message = f"Missing closing summary tag around line {line_number}"
-                error = True
-            if b"</summary>" in line and not after_summary:
-                err_message = f"Missing opening summary tag around line {line_number}"
-                error = True
-
-            if b"<summary>" in line:
-                after_summary = True
-
-            if b"</summary>" in line and after_summary:
-                after_summary = False
-
-        if error:
-            errors.append(err_message)
-
-        error = False
+    if args.verbose:
+        logger.setLevel(logging.DEBUG)
 
+    # Validate file extension
+    if not args.file_path.endswith(('.md', '.markdown')):
+        logger.error("Error: File must be a markdown file (.md or .markdown)")
+        return 1
 
-def check_md_file(file_name):
-    with open(p, "rb") as f:
-        file_list = [line.rstrip() for line in f.readlines()]
-    check_details_tag(file_list)
-    check_summary_tag(file_list)
+    # Initialize and run linter
+    linter = MarkdownLinter()
+    success = linter.validate_file(args.file_path)
+    linter.print_errors(args.file_path)
 
+    return 0 if success else 1
 
 if __name__ == "__main__":
-    print(f"..........Checking {p}..........")
-    check_md_file(p)
-    if errors:
-        print(f"{p} failed", file=sys.stderr)
-        for error in errors:
-            print(error, file=sys.stderr)
-        exit(1)
-
-    print("Tests passed successfully.")
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:
+        logger.info("\nLinting interrupted by user")
+        sys.exit(130)
+    except Exception as e:
+        logger.error(f"Unexpected error: {str(e)}")
+        sys.exit(1)