From 37efbcb069bda76f51bf092e7e1be35e2b02f05e Mon Sep 17 00:00:00 2001 From: nvaldez Date: Sun, 20 Sep 2026 14:50:10 +0200 Subject: [PATCH] Add mdoctor chklint command to check markdown files for lint violations - Add list_all_md_files() method to MDoctor class using Librarian.list_all_md_files() - Add check_markdown_lint() method to run markdownlint/pymarkdownlnt on .md files - Add chklint subcommand to mdoctor CLI with directory argument - Update fiona/__main__.py to pass subcommands to mdoctor - Add test_list_all_md_files() test in test_librarian.py Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- src/fiona/__main__.py | 10 ++- src/librarian/librarian.py | 17 ++++ src/mdoctor/mdoctor.py | 155 +++++++++++++++++++++++++++++++++--- src/tests/test_librarian.py | 36 +++++++++ 4 files changed, 202 insertions(+), 16 deletions(-) diff --git a/src/fiona/__main__.py b/src/fiona/__main__.py index 864b4c2..96e64f8 100644 --- a/src/fiona/__main__.py +++ b/src/fiona/__main__.py @@ -30,10 +30,11 @@ def main(): # fiona-assistant mdoctor mdoctor_parser = subparsers.add_parser("mdoctor", help="Diagnose wiki content") mdoctor_parser.add_argument( - "directory", - help="Directory to scan for files" + "args", + nargs=argparse.REMAINDER, + help="Subcommand and arguments for mdoctor (e.g., chklint /path/to/dir)" ) - + args = parser.parse_args() if args.command is None: @@ -44,7 +45,8 @@ def main(): sys.argv = ["librarian", args.directory] librarian_main() elif args.command == "mdoctor": - sys.argv = ["mdoctor", args.directory] + # Pass all remaining args to mdoctor + sys.argv = ["mdoctor"] + args.args mdoctor_main() else: parser.print_help() diff --git a/src/librarian/librarian.py b/src/librarian/librarian.py index 91576e5..cc549cb 100644 --- a/src/librarian/librarian.py +++ b/src/librarian/librarian.py @@ -26,6 +26,23 @@ class Librarian: file_list.append(os.path.join(root, file)) return file_list + def list_all_md_files(self, directory: str) -> list[str]: + """ + List all .md files in the given directory and its subdirectories. + + Args: + directory: Path to the directory to scan + + Returns: + List of absolute file paths for all .md files in the directory + """ + md_files = [] + for root, _, files in os.walk(directory): + for file in files: + if file.endswith('.md'): + md_files.append(os.path.join(root, file)) + return md_files + def main(): """Command-line interface for the librarian.""" diff --git a/src/mdoctor/mdoctor.py b/src/mdoctor/mdoctor.py index e9afb93..498d75e 100644 --- a/src/mdoctor/mdoctor.py +++ b/src/mdoctor/mdoctor.py @@ -2,41 +2,172 @@ MDoctor - A tool for diagnosing and managing the LLM wiki. """ import argparse +import json import os +import re +import shutil +import subprocess import sys from librarian.librarian import Librarian + class MDoctor: """Core class for diagnosing wiki content and operations.""" def __init__(self) -> None: self.librarian = Librarian() - - def list_all_files(self, directory: str): + def list_all_files(self, directory: str) -> list[str]: """List all files in the given directory using the librarian.""" return self.librarian.list_all_files(directory) + def list_all_md_files(self, directory: str) -> list[str]: + """List all .md files in the given directory using the librarian.""" + return self.librarian.list_all_md_files(directory) + + def _get_linter_command(self) -> list[str]: + """Get the available markdown linter command.""" + # Try markdownlint first (node-based, supports --json) + if shutil.which("markdownlint"): + return ["markdownlint", "--json"] + # Fall back to pymarkdownlnt (Python-based, use scan subcommand) + if shutil.which("pymarkdownlnt"): + return ["pymarkdownlnt", "scan"] + # No linter found + return [] + + def _parse_pymarkdownlnt_output(self, output: str) -> list[str]: + """Parse pymarkdownlnt output into list of error strings.""" + violations = [] + # pymarkdownlnt output format: "FILE:LINE: RULE: message" + for line in output.split('\n'): + line = line.strip() + if not line or ':' not in line: + continue + violations.append(line) + return violations + + def _parse_markdownlint_output(self, output: str) -> list[str]: + """Parse markdownlint JSON output into list of error strings.""" + violations = [] + try: + lint_errors = json.loads(output) + for error in lint_errors: + line = error.get("line", error.get("line-number", "?")) + rule = error.get("rule", error.get("rule-id", "?")) + rule_description = error.get("ruleDescription", "") + message = error.get("message", "") + violations.append(f"Line {line}: {rule} - {rule_description} ({message})") + except (json.JSONDecodeError, TypeError): + if output: + violations = [line.strip() for line in output.split('\n') if line.strip()] + return violations + + def check_markdown_lint(self, directory: str) -> dict[str, list[str]]: + """ + Run markdownlint on all .md files in the given directory. + + Args: + directory: Path to the directory to scan + + Returns: + Dictionary mapping file paths to lists of lint violations + """ + linter_cmd = self._get_linter_command() + if not linter_cmd: + print("Error: No markdown linter found. " + "Please install 'markdownlint-cli' (npm install -g markdownlint-cli) " + "or 'pymarkdownlnt' (pip install pymarkdownlnt).", file=sys.stderr) + sys.exit(1) + + is_markdownlint = linter_cmd[0] == "markdownlint" + + md_files = self.list_all_md_files(directory) + violations: dict[str, list[str]] = {} + + for md_file in md_files: + try: + # Run linter on the file + result = subprocess.run( + linter_cmd + [md_file], + capture_output=True, + text=True + ) + + # Parse output based on linter + if is_markdownlint: + errors = self._parse_markdownlint_output(result.stdout) + else: + # pymarkdownlnt outputs to stderr + output = result.stderr or result.stdout + errors = self._parse_pymarkdownlnt_output(output) + + if errors: + violations[md_file] = errors + except Exception as e: + violations[md_file] = [f"Error checking file: {str(e)}"] + + return violations + + def main(): """Command-line interface for the MDoctor tool.""" parser = argparse.ArgumentParser( description="MDoctor - A tool for diagnosing and managing the LLM wiki." ) - parser.add_argument( + subparsers = parser.add_subparsers(dest="subcommand", help="Available subcommands") + + # Default command: list all files + subparsers.add_parser("list", help="List all files in a directory") + + # chklint subcommand + chklint_parser = subparsers.add_parser("chklint", help="Check markdown files for lint violations") + chklint_parser.add_argument( "directory", - help="Directory to scan for files" + nargs="?", + default=".", + help="Directory to scan for markdown files (default: current directory)" ) + args = parser.parse_args() - - if not os.path.isdir(args.directory): - print(f"Error: '{args.directory}' is not a valid directory.", file=sys.stderr) + + if args.subcommand is None: + # Default behavior: list files + parser.print_help() sys.exit(1) - + mdoctor = MDoctor() - files = mdoctor.list_all_files(args.directory) - print(f"MDoctor: Found {len(files)} files in '{args.directory}':") - for file_path in files: - print(f" - {file_path}") + + if args.subcommand == "list": + # For backward compatibility, if no directory argument, use current dir + if not hasattr(args, 'directory'): + args.directory = "." + if not os.path.isdir(args.directory): + print(f"Error: '{args.directory}' is not a valid directory.", file=sys.stderr) + sys.exit(1) + files = mdoctor.list_all_files(args.directory) + print(f"MDoctor: Found {len(files)} files in '{args.directory}':") + for file_path in files: + print(f" - {file_path}") + + elif args.subcommand == "chklint": + directory = args.directory + if not os.path.isdir(directory): + print(f"Error: '{directory}' is not a valid directory.", file=sys.stderr) + sys.exit(1) + + violations = mdoctor.check_markdown_lint(directory) + + if not violations: + print(f"No markdown lint violations found in '{directory}'") + else: + print(f"Found {len(violations)} files with markdown lint violations:") + for file_path, errors in violations.items(): + print(f"\n {file_path}:") + for error in errors: + print(f" - {error}") + + print(f"\nTotal violations: {sum(len(e) for e in violations.values())}") if __name__ == "__main__": diff --git a/src/tests/test_librarian.py b/src/tests/test_librarian.py index f193459..71c9764 100644 --- a/src/tests/test_librarian.py +++ b/src/tests/test_librarian.py @@ -18,3 +18,39 @@ def test_list_all_files(librarian, temp_dir_with_files): assert len(files) == 3 for file_path in test_files: assert file_path in files + +def test_list_all_md_files(): + """Test that list_all_md_files() correctly lists only .md files recursively.""" + librarian = Librarian() + + with tempfile.TemporaryDirectory() as temp_dir: + # Create a mix of files + md_files = [ + os.path.join(temp_dir, "readme.md"), + os.path.join(temp_dir, "docs", "guide.md"), + os.path.join(temp_dir, "docs", "api.md"), + ] + other_files = [ + os.path.join(temp_dir, "setup.py"), + os.path.join(temp_dir, "docs", "config.json"), + os.path.join(temp_dir, "data", "notes.txt"), + ] + all_files = md_files + other_files + + # Create directory structure + for file_path in all_files: + os.makedirs(os.path.dirname(file_path), exist_ok=True) + with open(file_path, 'w') as f: + f.write("test content") + + # Call the method to get only .md files + found_md_files = librarian.list_all_md_files(temp_dir) + + # Verify only .md files are returned + assert len(found_md_files) == 3 + for md_file in md_files: + assert md_file in found_md_files + + # Verify no non-md files are returned + for other_file in other_files: + assert other_file not in found_md_files \ No newline at end of file