Files
fiona-assistant/tests/test_mdoctor.py
T

643 lines
26 KiB
Python

"""Tests for the MDoctor tool."""
import json
import os
import pathlib
import subprocess
import tempfile
from unittest.mock import patch
import pytest
from pymarkdown.api import PyMarkdownApiException
from fiona.mdoctor.mdoctor import MDoctor, ProgrammaticLintViolation, main
class TestMDoctor:
def test_scan_file_programmatically(self, markdownlint_actual_violations):
violations, _root_path = markdownlint_actual_violations
assert violations[0]['scan_file'] == '.'
assert violations[0]['line'] == 4
assert violations[0]['column'] == 1
assert violations[0]['rule_id'] == 'MD022'
assert violations[0]['rule_name'] == 'blanks-around-headings,blanks-around-headers'
assert violations[0]['description'] == 'Headings should be surrounded by blank lines.'
assert violations[0]['extra'] == ' [Expected: 1; Actual: 0; Below]'
def test_compress_violations(self, mdoctor, compressed_violations_no_extra):
compressed_violations = compressed_violations_no_extra
assert compressed_violations["files"] == {
'file1.md' : [
"1:1 MD100",
"2:1 MD200",
],
'file2.md' : [
"2:1 MD400",
"3:1 MD300",
],
}
assert compressed_violations["descriptions"] == {
"MD100": {
'rule_name': 'rule_name_01',
'description': 'description_01'
},
"MD200": {
'rule_name': 'rule_name_02',
'description': 'description_02'
},
"MD300": {
'rule_name': 'rule_name_03',
'description': 'description_03'
},
"MD400": {
'rule_name': 'rule_name_04',
'description': 'description_04'
},
}
assert compressed_violations["meta"] == {
"file_count": 2,
"total_violations": 4
}
def test_format_violations(self, mdoctor, compressed_violations_no_extra):
formated_str = mdoctor.format_violations(compressed_violations_no_extra).splitlines()
assert formated_str[1] == "- DEFINITIONS:"
assert formated_str[2] == " - MD100: rule_name_01, description_01"
assert formated_str[3] == " - MD200: rule_name_02, description_02"
assert formated_str[7] == "- FILE: file1.md"
assert formated_str[8] == " - 1:1 MD100"
assert formated_str[9] == " - 2:1 MD200"
assert formated_str[10] == "- FILE: file2.md"
assert formated_str[11] == " - 2:1 MD400"
assert formated_str[12] == " - 3:1 MD300"
class TestMDoctorMain:
"""Tests for mdoctor.main() function."""
def test_main_invalid_directory(self, capsys):
"""Test main() with invalid directory for list subcommand."""
with patch('sys.argv', ['mdoctor', 'list', '/nonexistent/directory']):
with pytest.raises(SystemExit) as exc_info:
main()
assert exc_info.value.code == 1
captured = capsys.readouterr()
assert "not a valid directory" in captured.err
def test_main_list_valid_directory(self, capsys):
"""Test main() with list subcommand and valid directory."""
with tempfile.TemporaryDirectory() as temp_dir:
# Create a test file
test_file = os.path.join(temp_dir, "test.txt")
with open(test_file, 'w') as f:
f.write("test content")
with patch('sys.argv', ['mdoctor', 'list', temp_dir]):
main()
captured = capsys.readouterr()
assert "Found" in captured.out
assert "files" in captured.out
def test_main_chklint_valid_directory(self, capsys):
"""Test main() with chklint subcommand and valid directory."""
with tempfile.TemporaryDirectory() as temp_dir:
# Create a test markdown file with valid content
test_file = os.path.join(temp_dir, "test.md")
with open(test_file, 'w') as f:
f.write("# Test Header\n\nContent here\n")
with patch('sys.argv', ['mdoctor', 'chklint', temp_dir]):
main()
captured = capsys.readouterr()
# Should output the violations report
assert "PyMarkdownLint Violations" in captured.out or "TARGET" in captured.out
def test_main_chklint_with_violations(self, capsys):
"""Test main() with chklint on file that has violations."""
with tempfile.TemporaryDirectory() as temp_dir:
# Create a test markdown file with violation (no blank line around header)
test_file = os.path.join(temp_dir, "test.md")
with open(test_file, 'w') as f:
f.write("#Header without space\nContent here\n")
with patch('sys.argv', ['mdoctor', 'chklint', temp_dir]):
main()
captured = capsys.readouterr()
# Should detect violations
assert "Violation" in captured.out or "MD022" in captured.out or "errors" in captured.out.lower()
def test_main_default_no_args(self, capsys):
"""Test main() with no arguments defaults to chklint."""
with tempfile.TemporaryDirectory() as temp_dir:
# Create a test markdown file
test_file = os.path.join(temp_dir, "test.md")
with open(test_file, 'w') as f:
f.write("# Test\n")
# Change to temp directory
original_dir = os.getcwd()
os.chdir(temp_dir)
try:
with patch('sys.argv', ['mdoctor']):
main()
captured = capsys.readouterr()
assert "PyMarkdownLint" in captured.out or "TARGET" in captured.out
finally:
os.chdir(original_dir)
class TestMDoctorSettings:
"""Tests for dynamic pymarkdown settings loading."""
LONG_LINE = " ".join(["word"] * 20) # 99 chars: over 80, under 100
def test_scan_applies_line_length_from_default_settings(self, mdoctor):
"""Lines up to the configured line_length are not MD013."""
with tempfile.TemporaryDirectory() as temp_dir:
test_file = os.path.join(temp_dir, "long.md")
with open(test_file, 'w') as f:
f.write(f"# Long lines\n\n{self.LONG_LINE}\n")
violations = mdoctor.scan_file_programmatically(test_file)
assert all(v["rule_id"] != "MD013" for v in violations)
def test_custom_settings_file(self, tmp_path):
"""Rule config is loaded dynamically from the given settings file."""
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text(json.dumps({
"markdown": {"pymarkdown": {"md013": {"line_length": 200}}}
}), encoding="utf-8")
md_file = tmp_path / "long.md"
md_file.write_text(f"# Long lines\n\n{self.LONG_LINE}\n", encoding="utf-8")
doctor = MDoctor(settings_file=settings_file)
violations = doctor.scan_file_programmatically(str(md_file))
assert all(v["rule_id"] != "MD013" for v in violations)
def test_missing_settings_file_uses_md013_defaults(self, tmp_path):
"""A missing settings file still uses line length 100."""
under = tmp_path / "under.md"
under.write_text(f"# Plain\n\n{self.LONG_LINE}\n", encoding="utf-8")
over = tmp_path / "over.md"
over.write_text("# Plain\n\n" + ("word " * 21) + "\n", encoding="utf-8")
doctor = MDoctor(settings_file=tmp_path / "no-settings.json")
under_hits = doctor.scan_file_programmatically(str(under))
over_hits = doctor.scan_file_programmatically(str(over))
assert all(v["rule_id"] != "MD013" for v in under_hits)
assert any(v["rule_id"] == "MD013" for v in over_hits)
def test_default_md013_ignores_table_rows(self, tmp_path):
"""Pipe rows over 100 characters are clean when tables stay off."""
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text("{}", encoding="utf-8")
row = "| " + ("cell " * 30) + " |"
prose = "word " * 21
md_file = tmp_path / "table.md"
md_file.write_text(f"# T\n\n{row}\n\n{prose}\n", encoding="utf-8")
doctor = MDoctor(settings_file=settings_file)
violations = doctor.scan_file_programmatically(str(md_file))
md013 = [v for v in violations if v["rule_id"] == "MD013"]
assert len(row) > 100
assert [v["line"] for v in md013] == [5]
def test_md013_tables_true_reports_long_table_rows(self, tmp_path):
"""tables true in the settings file reports a long pipe row."""
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text(json.dumps({
"markdown": {"pymarkdown": {"md013": {"line_length": 100, "tables": True}}}
}), encoding="utf-8")
row = "| " + ("cell " * 30) + " |"
md_file = tmp_path / "table.md"
md_file.write_text(f"# T\n\n{row}\n", encoding="utf-8")
doctor = MDoctor(settings_file=settings_file)
violations = doctor.scan_file_programmatically(str(md_file))
assert any(v["rule_id"] == "MD013" and v["line"] == 3 for v in violations)
def test_md013_still_checks_fenced_lines_when_code_blocks_on(self, tmp_path):
"""A fenced line is not treated as a table row."""
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text(json.dumps({
"markdown": {"pymarkdown": {
"md013": {"line_length": 100, "code_blocks": True, "tables": False}
}}
}), encoding="utf-8")
row = "| " + ("cell " * 30) + " |"
md_file = tmp_path / "fenced.md"
md_file.write_text(f"# T\n\n{row}\n\n```\n{row}\n```\n", encoding="utf-8")
doctor = MDoctor(settings_file=settings_file)
violations = doctor.scan_file_programmatically(str(md_file))
md013_lines = [v["line"] for v in violations if v["rule_id"] == "MD013"]
assert md013_lines == [6]
class TestMDoctorFix:
"""Tests for the mdoctor fix subcommand and fix method."""
def test_scan_file_programmatically_with_frontmatter(self, mdoctor):
"""Test scanning a file with YAML frontmatter raises no phantom violations."""
with tempfile.TemporaryDirectory() as temp_dir:
test_file = os.path.join(temp_dir, "frontmatter.md")
with open(test_file, 'w') as f:
f.write(
"---\n"
"name: Test\n"
"version: 1.0.0\n"
"---\n"
"\n"
"# Title\n"
"\n"
"Content here\n"
)
violations = mdoctor.scan_file_programmatically(test_file)
assert violations == []
def test_scan_title_frontmatter_with_body_h1(self, mdoctor):
"""Test a title in frontmatter plus one body h1 is not MD025."""
with tempfile.TemporaryDirectory() as temp_dir:
test_file = os.path.join(temp_dir, "titled.md")
with open(test_file, 'w') as f:
f.write(
"---\n"
"title: Page Title\n"
"---\n"
"\n"
"# Page Title\n"
"\n"
"Content here\n"
)
violations = mdoctor.scan_file_programmatically(test_file)
assert violations == []
def test_fix_file_programmatically_fixes_violations(self, mdoctor):
"""Test fix_file_programmatically applies auto-fixes and lists files."""
with tempfile.TemporaryDirectory() as temp_dir:
test_file = os.path.join(temp_dir, "test.md")
with open(test_file, 'w') as f:
f.write("# Test\n\nContent without trailing newline")
fixed_files = mdoctor.fix_file_programmatically(temp_dir)
assert test_file in fixed_files
with open(test_file, encoding="utf-8") as f:
assert f.read() == "# Test\n\nContent without trailing newline\n"
def test_fix_file_programmatically_clean_file(self, mdoctor):
"""Test fix_file_programmatically returns no files when nothing to fix."""
with tempfile.TemporaryDirectory() as temp_dir:
test_file = os.path.join(temp_dir, "test.md")
with open(test_file, 'w') as f:
f.write("# Test\n\nContent here\n")
fixed_files = mdoctor.fix_file_programmatically(temp_dir)
assert fixed_files == []
def test_main_fix_valid_directory(self, capsys):
"""Test main() with fix subcommand and a fixable file."""
with tempfile.TemporaryDirectory() as temp_dir:
test_file = os.path.join(temp_dir, "test.md")
with open(test_file, 'w') as f:
f.write("# Test\n\nContent without trailing newline")
with patch('sys.argv', ['mdoctor', 'fix', temp_dir]):
main()
captured = capsys.readouterr()
assert "1 file(s) fixed" in captured.out
assert "test.md" in captured.out
def test_main_fix_invalid_directory(self, capsys):
"""Test main() with fix subcommand and an invalid directory."""
with patch('sys.argv', ['mdoctor', 'fix', '/nonexistent/directory']):
with pytest.raises(SystemExit) as exc_info:
main()
assert exc_info.value.code == 1
captured = capsys.readouterr()
assert "not a valid directory" in captured.err
def test_main_fix_directory_without_md_files(self, capsys):
"""Test main() with fix on a directory containing no markdown files."""
with tempfile.TemporaryDirectory() as temp_dir:
with patch('sys.argv', ['mdoctor', 'fix', temp_dir]):
main()
captured = capsys.readouterr()
assert "0 file(s) fixed" in captured.out
def test_main_fix_reports_api_errors(self, capsys):
"""Test main() reports pymarkdown API failures instead of crashing."""
with tempfile.TemporaryDirectory() as temp_dir, \
patch('sys.argv', ['mdoctor', 'fix', temp_dir]), \
patch('fiona.mdoctor.mdoctor.MDoctor.fix_file_programmatically',
side_effect=PyMarkdownApiException("api failure")):
with pytest.raises(SystemExit) as exc_info:
main()
assert exc_info.value.code == 1
captured = capsys.readouterr()
assert "Error" in captured.err
assert "api failure" in captured.err
class TestMDoctorMethods:
"""Tests for MDoctor class methods."""
def test_list_all_md_files(self, mdoctor):
"""Test list_all_md_files method."""
with tempfile.TemporaryDirectory() as temp_dir:
# Create some markdown files
for i in range(3):
with open(os.path.join(temp_dir, f"file{i}.md"), 'w') as f:
f.write(f"# File {i}")
files = mdoctor.list_all_md_files(temp_dir)
assert len(files) == 3
# Check that all files are present (as Path objects)
file_names = [pathlib.Path(f).name for f in files]
assert all(f"file{i}.md" in file_names for i in range(3))
def test_scan_file_programmatically(self, mdoctor):
"""Test scan_file_programmatically method."""
with tempfile.TemporaryDirectory() as temp_dir:
# Create a markdown file
test_file = os.path.join(temp_dir, "test.md")
with open(test_file, 'w') as f:
f.write("# Test\n")
violations = mdoctor.scan_file_programmatically(test_file)
# Should return a list of violations (may be empty for valid file)
assert isinstance(violations, list)
def test_check_markdown_lint(self, mdoctor):
"""Test check_markdown_lint method."""
with tempfile.TemporaryDirectory() as temp_dir:
# Create a markdown file
test_file = os.path.join(temp_dir, "test.md")
with open(test_file, 'w') as f:
f.write("# Test\n")
result = mdoctor.check_markdown_lint(temp_dir)
# Should return a string with the formatted violations
assert isinstance(result, str)
def test_format_violations_empty(self, mdoctor):
"""Test format_violations with empty violations."""
result = mdoctor.format_violations({
"files": {},
"descriptions": {},
"meta": {"file_count": 0, "total_violations": 0}
})
assert "DEFINITIONS:" in result
assert "SUMMARY:" in result
assert "Total files with violations: 0" in result
def test_compress_violations_with_extra(self, mdoctor):
"""Test compress_violations with extra info."""
violations = [
{
'scan_file': 'file1.md',
'line': 1,
'column': 1,
'rule_id': 'MD100',
'rule_name': 'test_rule',
'description': 'test description',
'extra': 'extra info'
}
]
result = mdoctor.compress_violations(violations, put_extra=True)
assert "file1.md" in result["files"]
assert "extra info" in result["files"]["file1.md"][0]
def test_compress_violations_without_extra(self, mdoctor):
"""Test compress_violations without extra info."""
violations = [
{
'scan_file': 'file1.md',
'line': 1,
'column': 1,
'rule_id': 'MD100',
'rule_name': 'test_rule',
'description': 'test description',
'extra': 'extra info'
}
]
result = mdoctor.compress_violations(violations, put_extra=False)
assert "file1.md" in result["files"]
assert "extra info" not in result["files"]["file1.md"][0]
class TestProgrammaticLintViolation:
"""Tests for the ProgrammaticLintViolation record."""
def test_fields_and_repr(self):
"""Test the violation stores its fields and reprs them."""
violation = ProgrammaticLintViolation(
3, 1, "MD022", "blanks-around-headings", "Headings need blanks."
)
assert violation.line_number == 3
assert violation.column_number == 1
assert violation.rule_id == "MD022"
assert "MD022" in repr(violation)
assert "L3:C1" in repr(violation)
class TestMDoctorCli:
"""Tests for mdoctor CLI edge branches."""
def test_main_chklint_invalid_directory(self, capsys):
"""Test main() with chklint subcommand and an invalid directory."""
with patch('sys.argv', ['mdoctor', 'chklint', '/nonexistent/directory']), \
pytest.raises(SystemExit) as exc_info:
main()
assert exc_info.value.code == 1
captured = capsys.readouterr()
assert "not a valid directory" in captured.err
class TestMDoctorGitignore:
"""Tests for gitignore-aware scanning configured via settings."""
def _make_git_repo(self, tmp_path):
"""Turn the temp directory into a git repo so .gitignore applies."""
subprocess.run(["git", "init", "-q", str(tmp_path)], check=False)
(tmp_path / ".gitignore").write_text("ignored/\n", encoding="utf-8")
ignored_dir = tmp_path / "ignored"
ignored_dir.mkdir()
(ignored_dir / "violated.md").write_text(
"# Title\n## Sub\n\n- a\n- b\ntext\n", encoding="utf-8")
(tmp_path / "clean.md").write_text("# Clean\n\nContent\n", encoding="utf-8")
def test_scan_skips_gitignored_files(self, tmp_path, monkeypatch):
"""Test gitignored markdown files are not scanned."""
self._make_git_repo(tmp_path)
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text(json.dumps({
"markdown": {"pymarkdown": {"respect_gitignore": True}}
}), encoding="utf-8")
# pymarkdown consults git from the process cwd, not the scan path
monkeypatch.chdir(tmp_path)
doctor = MDoctor(settings_file=str(settings_file))
violations = doctor.scan_file_programmatically(str(tmp_path))
assert violations == []
def test_scan_skips_gitignore_dirs_without_git(self, tmp_path):
"""Directory entries in .gitignore are skipped when git is absent."""
(tmp_path / ".gitignore").write_text(".venvs/\n", encoding="utf-8")
ignored = tmp_path / ".venvs"
ignored.mkdir()
(ignored / "LICENSE.md").write_text("license text\n", encoding="utf-8")
(tmp_path / "clean.md").write_text("# Clean\n\nContent\n", encoding="utf-8")
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text(json.dumps({
"markdown": {"pymarkdown": {"respect_gitignore": True}}
}), encoding="utf-8")
doctor = MDoctor(settings_file=str(settings_file))
violations = doctor.scan_file_programmatically(str(tmp_path))
assert violations == []
def test_scan_does_not_ask_pymarkdown_for_git(self, tmp_path, monkeypatch):
"""PyMarkdown is told not to run git, and ignored dirs are excluded.
Generated by AI/LLM: 2026-09-30 - directory globs replace git check-ignore.
"""
(tmp_path / ".gitignore").write_text("ignored/\n# note\n", encoding="utf-8")
(tmp_path / "clean.md").write_text("# Clean\n\nContent\n", encoding="utf-8")
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text(json.dumps({
"markdown": {"pymarkdown": {"respect_gitignore": True}}
}), encoding="utf-8")
monkeypatch.chdir(tmp_path)
doctor = MDoctor(settings_file=str(settings_file))
captured = {}
def fake_scan_path(**kwargs):
captured.update(kwargs)
return type("Result", (), {"scan_failures": []})()
monkeypatch.setattr(doctor.api, "scan_path", fake_scan_path)
doctor.scan_file_programmatically(str(tmp_path))
assert captured["respect_gitignore"] is False
assert ".git/" in captured["exclude_patterns"]
assert "ignored/" in captured["exclude_patterns"]
def test_scan_outside_workdir_omits_exclude_patterns(self, tmp_path, monkeypatch):
"""A scan outside the working directory does not pass exclude globs.
Generated by AI/LLM: 2026-09-30 - those globs are relative to the working directory.
"""
(tmp_path / ".gitignore").write_text(".venvs/\n", encoding="utf-8")
(tmp_path / "clean.md").write_text("# Clean\n\nContent\n", encoding="utf-8")
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text(json.dumps({
"markdown": {"pymarkdown": {"respect_gitignore": True}}
}), encoding="utf-8")
doctor = MDoctor(settings_file=str(settings_file))
captured = {}
def fake_scan_path(**kwargs):
captured.update(kwargs)
return type("Result", (), {"scan_failures": []})()
monkeypatch.setattr(doctor.api, "scan_path", fake_scan_path)
doctor.scan_file_programmatically(str(tmp_path))
assert captured["respect_gitignore"] is False
assert captured["exclude_patterns"] is None
def test_scan_without_gitignore_setting_includes_ignored_files(self, tmp_path, monkeypatch):
"""Test files in ignored dirs are scanned without the setting."""
self._make_git_repo(tmp_path)
settings_file = tmp_path / "fiona-settings.json"
settings_file.write_text(json.dumps({
"markdown": {"pymarkdown": {}}
}), encoding="utf-8")
monkeypatch.chdir(tmp_path)
doctor = MDoctor(settings_file=str(settings_file))
violations = doctor.scan_file_programmatically(str(tmp_path))
assert len(violations) > 0
class TestFormatViolationsTarget:
"""Tests for the TARGET line in the mdoctor report."""
def _one_violation(self):
return [{
"scan_file": "src/llm-wiki/AGENTS.md",
"line": 17,
"column": 1,
"rule_id": "MD013",
"rule_name": "line-length",
"description": "Line length",
"extra": "",
}]
def test_compress_violations_stores_target(self, mdoctor):
"""Test the scanned target is stored in the compressed meta."""
result = mdoctor.compress_violations(
self._one_violation(), target="/repo/root"
)
expected = pathlib.Path("/repo/root").resolve().as_posix()
assert result["meta"]["target"] == expected
def test_compress_violations_without_target(self, mdoctor):
"""Test the meta has no target key when none is given."""
result = mdoctor.compress_violations(self._one_violation())
assert "target" not in result["meta"]
def test_format_violations_prints_target(self, mdoctor):
"""Test the report names the directory FILE paths are relative to."""
compressed = mdoctor.compress_violations(
self._one_violation(), target="/repo/root"
)
output = mdoctor.format_violations(compressed)
expected = pathlib.Path("/repo/root").resolve().as_posix()
assert f"TARGET: {expected}" in output
assert "- FILE: src/llm-wiki/AGENTS.md" in output
def test_format_violations_omits_target_when_absent(self, mdoctor):
"""Test no TARGET line is printed without a target."""
compressed = mdoctor.compress_violations(self._one_violation())
output = mdoctor.format_violations(compressed)
assert "TARGET:" not in output