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 <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-09-20 14:50:10 +02:00
parent 87b9b27f45
commit 37efbcb069
4 changed files with 202 additions and 16 deletions
+6 -4
View File
@@ -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()
+17
View File
@@ -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."""
+143 -12
View File
@@ -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__":
+36
View File
@@ -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