1701 lines
63 KiB
Python
1701 lines
63 KiB
Python
"""Tests for toc_generator module.
|
|
|
|
This module tests the table of contents generation functionality
|
|
for markdown files.
|
|
"""
|
|
|
|
import json
|
|
import logging
|
|
import pathlib
|
|
import re
|
|
import sys
|
|
import tempfile
|
|
|
|
import pytest
|
|
|
|
from fiona.librarian import toc_generator
|
|
from fiona.librarian.toc_generator import (
|
|
FILE_TOC_END,
|
|
FILE_TOC_START,
|
|
TOC_NAME,
|
|
FileTocConfig,
|
|
_get_version,
|
|
build_file_toc_lines,
|
|
build_toc,
|
|
collect_md,
|
|
depth_setting,
|
|
excluded,
|
|
file_toc_marker,
|
|
file_toc_params,
|
|
find_wiki_root,
|
|
generate_file_toc,
|
|
generate_file_tocs,
|
|
load_toc_settings,
|
|
main,
|
|
parse_file_toc_marker,
|
|
read_headers,
|
|
resolve_file_toc_config,
|
|
slugify,
|
|
strip_section_number,
|
|
target_folders,
|
|
)
|
|
|
|
# =============================================================================
|
|
# Fixtures
|
|
# =============================================================================
|
|
|
|
@pytest.fixture
|
|
def temp_dir_with_md_files():
|
|
"""Create a temporary directory with markdown files."""
|
|
with tempfile.TemporaryDirectory() as tmpdir:
|
|
tmpdir = pathlib.Path(tmpdir)
|
|
|
|
# Create some markdown files
|
|
(tmpdir / "file1.md").write_text("# Header 1\n## Subheader 1\n")
|
|
(tmpdir / "file2.md").write_text("# Header 2\n")
|
|
|
|
# Create subdirectory with files
|
|
subdir = tmpdir / "subdir"
|
|
subdir.mkdir()
|
|
(subdir / "file3.md").write_text("# Header 3\n## Subheader 3\n")
|
|
|
|
yield tmpdir
|
|
|
|
|
|
@pytest.fixture
|
|
def temp_dir_with_code_fences():
|
|
"""Create a temporary directory with markdown files containing code fences."""
|
|
with tempfile.TemporaryDirectory() as tmpdir:
|
|
tmpdir = pathlib.Path(tmpdir)
|
|
|
|
content = """# Main Header
|
|
|
|
```python
|
|
def hello():
|
|
pass
|
|
```
|
|
|
|
## Code Block Header
|
|
|
|
~~~bash
|
|
echo "test"
|
|
~~~
|
|
|
|
# After Fence Header
|
|
"""
|
|
(tmpdir / "with_fences.md").write_text(content)
|
|
|
|
yield tmpdir
|
|
|
|
|
|
@pytest.fixture
|
|
def temp_dir_with_hidden_files():
|
|
"""Create a temporary directory with hidden markdown files."""
|
|
with tempfile.TemporaryDirectory() as tmpdir:
|
|
tmpdir = pathlib.Path(tmpdir)
|
|
|
|
(tmpdir / ".hidden.md").write_text("# Hidden Header\n")
|
|
(tmpdir / "visible.md").write_text("# Visible Header\n")
|
|
|
|
subdir = tmpdir / ".hidden_dir"
|
|
subdir.mkdir()
|
|
(subdir / "file.md").write_text("# Hidden Dir File\n")
|
|
|
|
yield tmpdir
|
|
|
|
|
|
# =============================================================================
|
|
# Test: slugify
|
|
# =============================================================================
|
|
|
|
class TestSlugify:
|
|
"""Tests for slugify function."""
|
|
|
|
def test_slugify_simple_text(self):
|
|
"""Should convert simple text to slug."""
|
|
result = slugify("Hello World")
|
|
assert result == "hello-world"
|
|
|
|
def test_slugify_with_special_chars(self):
|
|
"""Should remove special characters."""
|
|
result = slugify("Hello, World!")
|
|
assert result == "hello-world"
|
|
|
|
def test_slugify_with_underscores(self):
|
|
"""Should preserve underscores."""
|
|
result = slugify("Hello_World")
|
|
assert result == "hello_world"
|
|
|
|
def test_slugify_with_hyphens(self):
|
|
"""Should preserve hyphens."""
|
|
result = slugify("Hello-World")
|
|
assert result == "hello-world"
|
|
|
|
def test_slugify_multiple_spaces(self):
|
|
"""Should collapse multiple spaces."""
|
|
result = slugify("Hello World")
|
|
assert result == "hello-world"
|
|
|
|
def test_slugify_lowercase(self):
|
|
"""Should convert to lowercase."""
|
|
result = slugify("HELLO WORLD")
|
|
assert result == "hello-world"
|
|
|
|
def test_slugify_with_numbers(self):
|
|
"""Should preserve numbers."""
|
|
result = slugify("Chapter 1: Introduction")
|
|
assert result == "chapter-1-introduction"
|
|
|
|
def test_slugify_empty_string(self):
|
|
"""Should handle empty string."""
|
|
result = slugify("")
|
|
assert result == ""
|
|
|
|
def test_slugify_with_hash_symbols(self):
|
|
"""Should remove hash symbols from header text."""
|
|
result = slugify("Title #1")
|
|
assert result == "title-1"
|
|
|
|
|
|
# =============================================================================
|
|
# Test: excluded
|
|
# =============================================================================
|
|
|
|
class TestExcluded:
|
|
"""Tests for excluded function."""
|
|
|
|
def test_excluded_no_patterns(self):
|
|
"""Should return False when no patterns."""
|
|
result = excluded("test.md", [])
|
|
assert result is False
|
|
|
|
def test_excluded_matching_pattern(self):
|
|
"""Should return True when pattern matches."""
|
|
patterns = [re.compile(r"test")]
|
|
result = excluded("test.md", patterns)
|
|
assert result is True
|
|
|
|
def test_excluded_non_matching_pattern(self):
|
|
"""Should return False when pattern doesn't match."""
|
|
patterns = [re.compile(r"other")]
|
|
result = excluded("test.md", patterns)
|
|
assert result is False
|
|
|
|
def test_excluded_multiple_patterns(self):
|
|
"""Should return True if any pattern matches."""
|
|
patterns = [re.compile(r"foo"), re.compile(r"bar")]
|
|
result = excluded("bar.md", patterns)
|
|
assert result is True
|
|
|
|
|
|
# =============================================================================
|
|
# Test: read_headers
|
|
# =============================================================================
|
|
|
|
class TestReadHeaders:
|
|
"""Tests for read_headers function."""
|
|
|
|
def test_read_headers_basic(self, temp_dir_with_md_files):
|
|
"""Should read headers from markdown file."""
|
|
filepath = temp_dir_with_md_files / "file1.md"
|
|
headers = read_headers(filepath)
|
|
|
|
assert len(headers) == 2
|
|
assert headers[0] == (1, "Header 1")
|
|
assert headers[1] == (2, "Subheader 1")
|
|
|
|
def test_read_headers_with_code_fences(self, temp_dir_with_code_fences):
|
|
"""Should skip headers inside code fences."""
|
|
filepath = temp_dir_with_code_fences / "with_fences.md"
|
|
headers = read_headers(filepath)
|
|
|
|
# Should have: Main Header, Code Block Header, After Fence Header
|
|
# Should NOT have: def hello() or echo "test"
|
|
header_texts = [text for _, text in headers]
|
|
|
|
assert "Main Header" in header_texts
|
|
assert "Code Block Header" in header_texts
|
|
assert "After Fence Header" in header_texts
|
|
assert "def hello()" not in header_texts
|
|
|
|
def test_read_headers_empty_file(self):
|
|
"""Should return empty list for file with no headers."""
|
|
with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
|
|
f.write("No headers here\n")
|
|
f.flush()
|
|
filepath = pathlib.Path(f.name)
|
|
|
|
try:
|
|
headers = read_headers(filepath)
|
|
assert headers == []
|
|
finally:
|
|
filepath.unlink()
|
|
|
|
def test_read_headers_various_levels(self):
|
|
"""Should handle various header levels."""
|
|
with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
|
|
f.write("# Level 1\n## Level 2\n### Level 3\n#### Level 4\n##### Level 5\n###### Level 6\n")
|
|
f.flush()
|
|
filepath = pathlib.Path(f.name)
|
|
|
|
try:
|
|
headers = read_headers(filepath)
|
|
assert len(headers) == 6
|
|
for i, (level, _) in enumerate(headers):
|
|
assert level == i + 1
|
|
finally:
|
|
filepath.unlink()
|
|
|
|
|
|
# =============================================================================
|
|
# Test: collect_md
|
|
# =============================================================================
|
|
|
|
class TestCollectMd:
|
|
"""Tests for collect_md function."""
|
|
|
|
def test_collect_md_recursive(self, temp_dir_with_md_files):
|
|
"""Should collect markdown files recursively."""
|
|
files = collect_md(temp_dir_with_md_files, [], recursive=True)
|
|
|
|
assert "file1.md" in files
|
|
assert "file2.md" in files
|
|
assert "subdir/file3.md" in files
|
|
assert len(files) == 3
|
|
|
|
def test_collect_md_non_recursive(self, temp_dir_with_md_files):
|
|
"""Should collect only top-level markdown files."""
|
|
files = collect_md(temp_dir_with_md_files, [], recursive=False)
|
|
|
|
assert "file1.md" in files
|
|
assert "file2.md" in files
|
|
assert "subdir/file3.md" not in files
|
|
assert len(files) == 2
|
|
|
|
def test_collect_md_exclude_toc(self, temp_dir_with_md_files):
|
|
"""Should exclude table_of_contents.md."""
|
|
# Create a toc file
|
|
toc_file = temp_dir_with_md_files / TOC_NAME
|
|
toc_file.write_text("# TOC\n")
|
|
|
|
files = collect_md(temp_dir_with_md_files, [], recursive=True)
|
|
|
|
assert TOC_NAME not in files
|
|
|
|
def test_collect_md_exclude_hidden(self, temp_dir_with_hidden_files):
|
|
"""Should exclude hidden files and directories."""
|
|
files = collect_md(temp_dir_with_hidden_files, [], recursive=True)
|
|
|
|
assert ".hidden.md" not in files
|
|
assert "visible.md" in files
|
|
assert len(files) == 1
|
|
|
|
def test_collect_md_with_exclude_pattern(self, temp_dir_with_md_files):
|
|
"""Should exclude files matching pattern."""
|
|
patterns = [re.compile(r"file1")]
|
|
files = collect_md(temp_dir_with_md_files, patterns, recursive=True)
|
|
|
|
assert "file1.md" not in files
|
|
assert "file2.md" in files
|
|
assert "subdir/file3.md" in files
|
|
|
|
def test_collect_md_empty_directory(self):
|
|
"""Should return empty list for directory with no md files."""
|
|
with tempfile.TemporaryDirectory() as tmpdir:
|
|
files = collect_md(pathlib.Path(tmpdir), [], recursive=True)
|
|
assert files == []
|
|
|
|
|
|
# =============================================================================
|
|
# Test: build_toc
|
|
# =============================================================================
|
|
|
|
class TestBuildToc:
|
|
"""Tests for build_toc function."""
|
|
|
|
def test_build_toc_single_file(self, temp_dir_with_md_files):
|
|
"""Should build TOC for single file."""
|
|
folder = temp_dir_with_md_files
|
|
files = ["file1.md"]
|
|
|
|
result = build_toc(folder, files)
|
|
|
|
assert "# Table of Contents" in result
|
|
assert "- [file1.md](file1.md)" in result
|
|
|
|
def test_build_toc_with_headers(self, temp_dir_with_md_files):
|
|
"""Should include headers in TOC."""
|
|
folder = temp_dir_with_md_files
|
|
files = ["file1.md"]
|
|
|
|
result = build_toc(folder, files)
|
|
|
|
assert "# Table of Contents" in result
|
|
assert "- [file1.md](file1.md)" in result
|
|
assert "Header 1" in result
|
|
assert "Subheader 1" in result
|
|
|
|
def test_build_toc_nested_folders(self, temp_dir_with_md_files):
|
|
"""Should handle nested folder structure."""
|
|
folder = temp_dir_with_md_files
|
|
files = ["file1.md", "subdir/file3.md"]
|
|
|
|
result = build_toc(folder, files)
|
|
|
|
assert "# Table of Contents" in result
|
|
assert "- subdir" in result
|
|
assert "- [file3.md](subdir/file3.md)" in result
|
|
|
|
def test_build_toc_empty_files(self):
|
|
"""Should handle empty file list."""
|
|
folder = pathlib.Path("/test")
|
|
files = []
|
|
|
|
result = build_toc(folder, files)
|
|
|
|
# Result should include frontmatter and TOC header
|
|
assert "---" in result, "Result should include frontmatter delimiter"
|
|
assert "name: Table of Contents" in result, "Result should include name in frontmatter"
|
|
assert "version: 1.0.0" in result, "Result should include version in frontmatter"
|
|
assert "title: Table of Contents" in result, "Result should include title in frontmatter"
|
|
assert "# Table of Contents" in result, "Result should include TOC header"
|
|
|
|
|
|
# =============================================================================
|
|
# Test: target_folders
|
|
# =============================================================================
|
|
|
|
class TestTargetFolders:
|
|
"""Tests for target_folders function."""
|
|
|
|
def test_target_folders_single(self):
|
|
"""Should return single folder when not every."""
|
|
root = pathlib.Path("/test")
|
|
folders = target_folders(root, [], every=False)
|
|
|
|
assert len(folders) == 1
|
|
assert folders[0] == root
|
|
|
|
def test_target_folders_every(self):
|
|
"""Should return all folders when every=True."""
|
|
with tempfile.TemporaryDirectory() as tmpdir:
|
|
tmpdir = pathlib.Path(tmpdir)
|
|
|
|
# Create nested directories
|
|
(tmpdir / "sub1").mkdir()
|
|
(tmpdir / "sub1" / "sub2").mkdir()
|
|
|
|
folders = target_folders(tmpdir, [], every=True)
|
|
|
|
assert len(folders) >= 3
|
|
assert tmpdir in folders
|
|
assert (tmpdir / "sub1") in folders
|
|
assert (tmpdir / "sub1" / "sub2") in folders
|
|
|
|
def test_target_folders_with_exclude_pattern(self):
|
|
"""Should exclude folders matching pattern."""
|
|
with tempfile.TemporaryDirectory() as tmpdir:
|
|
tmpdir = pathlib.Path(tmpdir)
|
|
|
|
(tmpdir / "include").mkdir()
|
|
(tmpdir / "exclude_me").mkdir()
|
|
|
|
patterns = [re.compile(r"exclude")]
|
|
folders = target_folders(tmpdir, patterns, every=True)
|
|
|
|
folder_names = [f.name for f in folders]
|
|
assert "include" in folder_names
|
|
assert "exclude_me" not in folder_names
|
|
|
|
|
|
# =============================================================================
|
|
# Test: main function (Integration)
|
|
# =============================================================================
|
|
|
|
class TestMain:
|
|
"""Integration tests for main function."""
|
|
|
|
def test_main_default_directory(self, temp_dir_with_md_files, monkeypatch):
|
|
"""Should generate TOC in default directory."""
|
|
# Change to temp directory
|
|
monkeypatch.chdir(temp_dir_with_md_files)
|
|
|
|
# Run main with default arguments
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator"]
|
|
main()
|
|
|
|
# Check that TOC was created
|
|
toc_file = temp_dir_with_md_files / TOC_NAME
|
|
assert toc_file.exists()
|
|
|
|
content = toc_file.read_text()
|
|
assert "# Table of Contents" in content
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
def test_main_with_directory_arg(self, temp_dir_with_md_files):
|
|
"""Should generate TOC in specified directory."""
|
|
original_argv = sys.argv
|
|
|
|
try:
|
|
sys.argv = ["toc_generator", str(temp_dir_with_md_files)]
|
|
main()
|
|
|
|
# Check that TOC was created
|
|
toc_file = temp_dir_with_md_files / TOC_NAME
|
|
assert toc_file.exists()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
def test_main_recursive_toc(self, temp_dir_with_md_files):
|
|
"""Should generate TOC in every subfolder with -r flag."""
|
|
original_argv = sys.argv
|
|
|
|
try:
|
|
sys.argv = ["toc_generator", str(temp_dir_with_md_files), "-r"]
|
|
main()
|
|
|
|
# Check TOC in main directory
|
|
assert (temp_dir_with_md_files / TOC_NAME).exists()
|
|
|
|
# Check TOC in subdirectory
|
|
subdir = temp_dir_with_md_files / "subdir"
|
|
assert (subdir / TOC_NAME).exists()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
def test_main_non_recursive(self, temp_dir_with_md_files):
|
|
"""Should not include subdirectories with -n flag."""
|
|
original_argv = sys.argv
|
|
|
|
try:
|
|
sys.argv = ["toc_generator", str(temp_dir_with_md_files), "-n"]
|
|
main()
|
|
|
|
# Check TOC in main directory
|
|
assert (temp_dir_with_md_files / TOC_NAME).exists()
|
|
|
|
# Check NO TOC in subdirectory
|
|
subdir = temp_dir_with_md_files / "subdir"
|
|
assert not (subdir / TOC_NAME).exists()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
def test_main_with_exclude(self, temp_dir_with_md_files):
|
|
"""Should exclude files matching pattern."""
|
|
original_argv = sys.argv
|
|
|
|
try:
|
|
sys.argv = ["toc_generator", str(temp_dir_with_md_files), "-e", "file1"]
|
|
main()
|
|
|
|
toc_file = temp_dir_with_md_files / TOC_NAME
|
|
content = toc_file.read_text()
|
|
|
|
# file1.md should not be in TOC
|
|
assert "file1.md" not in content
|
|
# file2.md should be in TOC
|
|
assert "file2.md" in content
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
|
|
class TestTocFrontmatter:
|
|
"""Tests for TOC file frontmatter generation."""
|
|
|
|
def test_toc_file_has_frontmatter(self, temp_dir_with_md_files):
|
|
"""Test that generated TOC file includes YAML frontmatter."""
|
|
original_argv = sys.argv
|
|
|
|
try:
|
|
sys.argv = ["toc_generator", str(temp_dir_with_md_files)]
|
|
main()
|
|
|
|
toc_file = temp_dir_with_md_files / TOC_NAME
|
|
content = toc_file.read_text()
|
|
|
|
# AI/LLM: frontmatter grew past 100 characters once name and version were added.
|
|
preamble = content.split("# Table of Contents", 1)[0]
|
|
assert content.startswith("---"), "TOC should start with frontmatter delimiter"
|
|
assert preamble.count("---") >= 2, "TOC should have closing frontmatter delimiter"
|
|
|
|
assert "name: Table of Contents" in preamble, "TOC should have name in frontmatter"
|
|
assert "version: 1.0.0" in preamble, "TOC should have version in frontmatter"
|
|
assert "title:" in preamble, "TOC should have title in frontmatter"
|
|
assert "created:" in preamble or "date:" in preamble, "TOC should have date field in frontmatter"
|
|
assert "type:" in preamble, "TOC should have type field in frontmatter"
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
def test_toc_entries_include_version(self, temp_dir_with_md_files):
|
|
"""Test that TOC entries include file versions from frontmatter, or v0.0.0 if missing."""
|
|
original_argv = sys.argv
|
|
|
|
# Create files with and without version frontmatter
|
|
file_with_version = temp_dir_with_md_files / "file1.md"
|
|
file_with_version.write_text("""---
|
|
title: File 1
|
|
version: 1.0.0
|
|
---
|
|
# File 1
|
|
## Section 1
|
|
""")
|
|
|
|
file_without_version = temp_dir_with_md_files / "file2.md"
|
|
file_without_version.write_text("# File 2\n")
|
|
|
|
try:
|
|
sys.argv = ["toc_generator", str(temp_dir_with_md_files)]
|
|
main()
|
|
|
|
toc_file = temp_dir_with_md_files / TOC_NAME
|
|
content = toc_file.read_text()
|
|
|
|
# Check that entries include version
|
|
# file1.md has version 1.0.0
|
|
assert "v1.0.0" in content, "TOC should include version 1.0.0 for file1.md"
|
|
|
|
# file2.md has no version, should show v0.0.0
|
|
assert "v0.0.0" in content, "TOC should show v0.0.0 for files without version"
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
|
|
class TestGetVersion:
|
|
"""Tests for the _get_version frontmatter fallback."""
|
|
|
|
def test_get_version_returns_frontmatter_version(self, tmp_path):
|
|
"""Test _get_version reads the version field when present."""
|
|
md_file = tmp_path / "versioned.md"
|
|
md_file.write_text("---\nversion: 2.1.3\n---\n# Content\n", encoding="utf-8")
|
|
|
|
assert _get_version(md_file) == "v2.1.3"
|
|
|
|
def test_get_version_missing_file_returns_default(self):
|
|
"""Test _get_version returns v0.0.0 for a file that does not exist."""
|
|
assert _get_version(pathlib.Path("/nonexistent/file.md")) == "v0.0.0"
|
|
|
|
def test_get_version_malformed_frontmatter_returns_default(self, tmp_path):
|
|
"""Test _get_version returns v0.0.0 when the frontmatter is unparseable."""
|
|
md_file = tmp_path / "malformed.md"
|
|
md_file.write_text("---\nversion: [unclosed\n---\n# Content\n", encoding="utf-8")
|
|
|
|
assert _get_version(md_file) == "v0.0.0"
|
|
|
|
|
|
# =============================================================================
|
|
# Test: toc_generator settings (fiona-settings.json)
|
|
# =============================================================================
|
|
|
|
@pytest.fixture
|
|
def temp_dir_nested_depth():
|
|
"""Create a tree with markdown files at several directory depths."""
|
|
with tempfile.TemporaryDirectory() as tmpdir:
|
|
tmpdir = pathlib.Path(tmpdir)
|
|
|
|
(tmpdir / "top.md").write_text("# Top\n")
|
|
level1 = tmpdir / "level1"
|
|
level1.mkdir()
|
|
(level1 / "one.md").write_text("# One\n")
|
|
level2 = level1 / "level2"
|
|
level2.mkdir()
|
|
(level2 / "two.md").write_text("# Two\n")
|
|
|
|
yield tmpdir
|
|
|
|
|
|
class TestLoadTocSettings:
|
|
"""Tests for load_toc_settings."""
|
|
|
|
def test_load_toc_settings_reads_section(self, tmp_path):
|
|
"""Should return the toc_generator section of the settings file."""
|
|
settings_file = tmp_path / "fiona-settings.json"
|
|
settings_file.write_text(
|
|
json.dumps({"toc_generator": {"max_depth_from_file": 2, "max_depth_from_dir": 1}}),
|
|
encoding="utf-8",
|
|
)
|
|
|
|
settings = load_toc_settings(settings_file)
|
|
|
|
assert settings == {"max_depth_from_file": 2, "max_depth_from_dir": 1}
|
|
|
|
def test_load_toc_settings_missing_section_returns_empty(self, tmp_path):
|
|
"""Should return an empty dict when the file has no toc_generator section."""
|
|
settings_file = tmp_path / "fiona-settings.json"
|
|
settings_file.write_text("{}", encoding="utf-8")
|
|
|
|
assert load_toc_settings(settings_file) == {}
|
|
|
|
def test_load_toc_settings_missing_file_returns_empty(self, tmp_path):
|
|
"""Should return an empty dict (unlimited depths) when the file is missing."""
|
|
assert load_toc_settings(tmp_path / "missing.json") == {}
|
|
|
|
|
|
class TestDepthSetting:
|
|
"""Tests for depth_setting validation."""
|
|
|
|
def test_absent_key_returns_none(self):
|
|
"""Should return None (unlimited) when the key is absent."""
|
|
assert depth_setting({}, "max_depth_from_file") is None
|
|
|
|
def test_valid_value_returned(self):
|
|
"""Should return the configured non-negative integer."""
|
|
assert depth_setting({"max_depth_from_file": 3}, "max_depth_from_file") == 3
|
|
|
|
def test_zero_means_unlimited(self):
|
|
"""Should treat zero as unlimited, returning None."""
|
|
assert depth_setting({"max_depth_from_dir": 0}, "max_depth_from_dir") is None
|
|
|
|
def test_negative_raises(self):
|
|
"""Should raise ValueError on a negative depth."""
|
|
with pytest.raises(ValueError):
|
|
depth_setting({"max_depth_from_file": -1}, "max_depth_from_file")
|
|
|
|
def test_non_int_raises(self):
|
|
"""Should raise ValueError on a non-integer depth."""
|
|
with pytest.raises(ValueError):
|
|
depth_setting({"max_depth_from_dir": "deep"}, "max_depth_from_dir")
|
|
|
|
def test_bool_raises(self):
|
|
"""Should raise ValueError on a boolean depth."""
|
|
with pytest.raises(ValueError):
|
|
depth_setting({"max_depth_from_dir": True}, "max_depth_from_dir")
|
|
|
|
|
|
class TestCollectMdMaxDepth:
|
|
"""Tests for collect_md respecting max_depth_from_dir."""
|
|
|
|
def test_max_depth_zero_is_unlimited(self, temp_dir_nested_depth):
|
|
"""Should collect the whole tree when max_depth is zero."""
|
|
files = collect_md(temp_dir_nested_depth, [], recursive=True, max_depth=0)
|
|
|
|
assert files == ["level1/level2/two.md", "level1/one.md", "top.md"]
|
|
|
|
def test_max_depth_one(self, temp_dir_nested_depth):
|
|
"""Should collect files up to one subfolder level."""
|
|
files = collect_md(temp_dir_nested_depth, [], recursive=True, max_depth=1)
|
|
|
|
assert files == ["level1/one.md", "top.md"]
|
|
|
|
def test_none_is_unlimited(self, temp_dir_nested_depth):
|
|
"""Should collect the whole tree when max_depth is None."""
|
|
files = collect_md(temp_dir_nested_depth, [], recursive=True, max_depth=None)
|
|
|
|
assert files == ["level1/level2/two.md", "level1/one.md", "top.md"]
|
|
|
|
def test_non_recursive_ignores_max_depth(self, temp_dir_nested_depth):
|
|
"""Should still collect only direct files with recursive=False."""
|
|
files = collect_md(temp_dir_nested_depth, [], recursive=False, max_depth=5)
|
|
|
|
assert files == ["top.md"]
|
|
|
|
|
|
class TestBuildTocMaxHeaderDepth:
|
|
"""Tests for build_toc respecting max_depth_from_file."""
|
|
|
|
def test_headers_beyond_max_depth_omitted(self, tmp_path):
|
|
"""Should omit headers deeper than max_header_depth."""
|
|
md_file = tmp_path / "doc.md"
|
|
md_file.write_text("# H1\n## H2\n### H3\n#### H4\n", encoding="utf-8")
|
|
|
|
result = build_toc(tmp_path, ["doc.md"], max_header_depth=3)
|
|
|
|
assert "H3" in result
|
|
assert "H4" not in result
|
|
|
|
def test_none_includes_all_levels(self, tmp_path):
|
|
"""Should include every header level when max_header_depth is None."""
|
|
md_file = tmp_path / "doc.md"
|
|
md_file.write_text("# H1\n## H2\n### H3\n#### H4\n", encoding="utf-8")
|
|
|
|
result = build_toc(tmp_path, ["doc.md"], max_header_depth=None)
|
|
|
|
assert "H3" in result
|
|
assert "H4" in result
|
|
|
|
def test_zero_is_unlimited(self, tmp_path):
|
|
"""Should include every header level when max_header_depth is zero."""
|
|
md_file = tmp_path / "doc.md"
|
|
md_file.write_text("# H1\n## H2\n### H3\n#### H4\n", encoding="utf-8")
|
|
|
|
result = build_toc(tmp_path, ["doc.md"], max_header_depth=0)
|
|
|
|
assert "H3" in result
|
|
assert "H4" in result
|
|
|
|
|
|
class TestMainSettings:
|
|
"""Integration tests for settings-driven depth limits in main()."""
|
|
|
|
def test_main_applies_packaged_settings(self, tmp_path):
|
|
"""Should honor the packaged fiona-settings.json depth limits.
|
|
|
|
The packaged template ships max_depth_from_file=3 (headers up to
|
|
level 3) and max_depth_from_dir=0 (unlimited recursion).
|
|
"""
|
|
(tmp_path / "doc.md").write_text("# H1\n## H2\n### H3\n#### H4\n", encoding="utf-8")
|
|
sub = tmp_path / "sub"
|
|
sub.mkdir()
|
|
(sub / "deep.md").write_text("# Deep\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", str(tmp_path)]
|
|
main()
|
|
|
|
content = (tmp_path / TOC_NAME).read_text(encoding="utf-8")
|
|
assert "H3" in content
|
|
assert "H4" not in content
|
|
assert "deep.md" in content
|
|
assert "sub" in content
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
def test_main_invalid_settings_exits_with_error(self, tmp_path, monkeypatch, capsys):
|
|
"""Should exit 1 with a clear stderr message on invalid settings."""
|
|
bad_settings = tmp_path / "fiona-settings.json"
|
|
bad_settings.write_text(
|
|
json.dumps({"toc_generator": {"max_depth_from_file": -2}}), encoding="utf-8"
|
|
)
|
|
monkeypatch.setattr(toc_generator, "DEFAULT_SETTINGS_FILE", bad_settings)
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", str(tmp_path)]
|
|
with pytest.raises(SystemExit) as excinfo:
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert excinfo.value.code == 1
|
|
assert "max_depth_from_file" in capsys.readouterr().err
|
|
|
|
|
|
# =============================================================================
|
|
# Test: per-file TOC generation (SPEC 7.3.1.2)
|
|
# =============================================================================
|
|
|
|
SAMPLE_DOC = """# Guide
|
|
|
|
intro text
|
|
|
|
## Section One
|
|
|
|
### Sub One
|
|
|
|
## Section Two
|
|
|
|
#### Deep
|
|
"""
|
|
|
|
|
|
@pytest.fixture
|
|
def sample_doc(tmp_path):
|
|
"""Create a markdown file with an H1 and nested headings."""
|
|
doc = tmp_path / "doc.md"
|
|
doc.write_text(SAMPLE_DOC, encoding="utf-8")
|
|
return doc
|
|
|
|
|
|
@pytest.fixture
|
|
def hermetic_settings(tmp_path, monkeypatch):
|
|
"""Pin the packaged-settings fallback for deterministic file TOCs.
|
|
|
|
The packaged template's toc_generator.file values (e.g.
|
|
sectionize) are user configuration; tests asserting exact entry
|
|
shapes must not depend on them.
|
|
"""
|
|
settings_file = tmp_path / "hermetic-settings.json"
|
|
settings_file.write_text(
|
|
json.dumps({"toc_generator": {"file": {"sectionize": False}}}),
|
|
encoding="utf-8",
|
|
)
|
|
monkeypatch.setattr(toc_generator, "DEFAULT_SETTINGS_FILE", settings_file)
|
|
return settings_file
|
|
|
|
|
|
class TestFileTocParams:
|
|
"""Tests for parsing the toc_generator.file settings section."""
|
|
|
|
def test_defaults_when_no_file_section(self):
|
|
"""Should return defaults and no overrides without a file section."""
|
|
config, overrides = file_toc_params({})
|
|
assert config == FileTocConfig()
|
|
assert overrides == []
|
|
|
|
def test_params_read_from_section(self):
|
|
"""Should read scalars and separate glob overrides."""
|
|
section = {
|
|
"min_heading": 3,
|
|
"max_heading": 4,
|
|
"sectionize": True,
|
|
"ignore_files": ["skip*"],
|
|
"*/rules.md": {"max_heading": 2},
|
|
}
|
|
config, overrides = file_toc_params({"file": section})
|
|
assert config.min_heading == 3
|
|
assert config.max_heading == 4
|
|
assert config.sectionize is True
|
|
assert config.ignore_files == ("skip*",)
|
|
assert overrides == [("*/rules.md", {"max_heading": 2})]
|
|
|
|
def test_min_heading_below_two_raises(self):
|
|
"""Should refuse min_heading 1 since H1 is never included."""
|
|
with pytest.raises(ValueError, match="min_heading"):
|
|
file_toc_params({"file": {"min_heading": 1}})
|
|
|
|
def test_non_int_heading_raises(self):
|
|
"""Should refuse non-integer heading bounds."""
|
|
with pytest.raises(ValueError, match="max_heading"):
|
|
file_toc_params({"file": {"max_heading": "six"}})
|
|
|
|
def test_bool_heading_raises(self):
|
|
"""Should refuse boolean heading bounds."""
|
|
with pytest.raises(ValueError, match="min_heading"):
|
|
file_toc_params({"file": {"min_heading": True}})
|
|
|
|
def test_min_greater_than_max_raises(self):
|
|
"""Should refuse min_heading above max_heading."""
|
|
with pytest.raises(ValueError, match="min_heading"):
|
|
file_toc_params({"file": {"min_heading": 5, "max_heading": 3}})
|
|
|
|
def test_non_bool_sectionize_raises(self):
|
|
"""Should refuse a non-boolean sectionize."""
|
|
with pytest.raises(ValueError, match="sectionize"):
|
|
file_toc_params({"file": {"sectionize": "yes"}})
|
|
|
|
def test_non_list_ignore_files_raises(self):
|
|
"""Should refuse a non-list ignore_files."""
|
|
with pytest.raises(ValueError, match="ignore_files"):
|
|
file_toc_params({"file": {"ignore_files": "skip.md"}})
|
|
|
|
def test_unknown_scalar_key_raises(self):
|
|
"""Should refuse unknown settings keys so typos fail loudly."""
|
|
with pytest.raises(ValueError, match="typo_key"):
|
|
file_toc_params({"file": {"typo_key": 1}})
|
|
|
|
def test_non_mapping_file_section_raises(self):
|
|
"""Should refuse a file section that is not a mapping."""
|
|
with pytest.raises(ValueError, match="toc_generator.file"):
|
|
file_toc_params({"file": [1, 2]})
|
|
|
|
|
|
class TestResolveFileTocConfig:
|
|
"""Tests for glob overrides in the toc_generator.file section."""
|
|
|
|
def test_matching_override_applied(self):
|
|
"""Should apply the override for a matching relative path."""
|
|
settings = {"file": {"max_heading": 6, "*/rules.md": {"max_heading": 2}}}
|
|
config = resolve_file_toc_config(settings, "sub/rules.md")
|
|
assert config.max_heading == 2
|
|
assert config.min_heading == 2
|
|
|
|
def test_non_matching_override_ignored(self):
|
|
"""Should keep global params for non-matching paths."""
|
|
settings = {"file": {"max_heading": 6, "*/rules.md": {"max_heading": 2}}}
|
|
config = resolve_file_toc_config(settings, "other.md")
|
|
assert config.max_heading == 6
|
|
|
|
def test_override_sectionize_applied(self):
|
|
"""Should override sectionize for matching paths."""
|
|
settings = {"file": {"sectionize": False, "guide.md": {"sectionize": True}}}
|
|
config = resolve_file_toc_config(settings, "guide.md")
|
|
assert config.sectionize is True
|
|
|
|
def test_override_unknown_key_raises(self):
|
|
"""Should refuse unknown keys inside a glob override."""
|
|
settings = {"file": {"*.md": {"typo": 1}}}
|
|
with pytest.raises(ValueError, match="typo"):
|
|
resolve_file_toc_config(settings, "a.md")
|
|
|
|
def test_invalid_global_params_raise(self):
|
|
"""Should validate global params even without overrides."""
|
|
with pytest.raises(ValueError, match="max_heading"):
|
|
resolve_file_toc_config({"file": {"max_heading": 9}}, "a.md")
|
|
|
|
|
|
class TestStripSectionNumber:
|
|
"""Tests for stripping existing section numbers from headings."""
|
|
|
|
def test_strips_single_number(self):
|
|
"""Should strip a '1. ' prefix."""
|
|
assert strip_section_number("1. Title") == "Title"
|
|
|
|
def test_strips_nested_number(self):
|
|
"""Should strip a '1.2. ' prefix."""
|
|
assert strip_section_number("1.2. Sub") == "Sub"
|
|
|
|
def test_strips_number_without_trailing_dot(self):
|
|
"""Should strip a '3.2 ' prefix."""
|
|
assert strip_section_number("3.2 Sub") == "Sub"
|
|
|
|
def test_plain_text_unchanged(self):
|
|
"""Should leave unnumbered headings alone."""
|
|
assert strip_section_number("Title") == "Title"
|
|
|
|
|
|
class TestBuildFileTocLines:
|
|
"""Tests for building the per-file TOC entry lines."""
|
|
|
|
def test_nesting_and_anchors(self):
|
|
"""Should nest by heading level and link GitHub-style anchors."""
|
|
headings = [(2, "Section One"), (3, "Sub One"), (2, "Section Two")]
|
|
lines = build_file_toc_lines(headings, FileTocConfig())
|
|
assert lines == [
|
|
"- [Section One](#section-one)",
|
|
" - [Sub One](#sub-one)",
|
|
"- [Section Two](#section-two)",
|
|
]
|
|
|
|
def test_min_heading_controls_indent(self):
|
|
"""Should treat min_heading as the unindented top level."""
|
|
headings = [(3, "Sub"), (4, "Deeper")]
|
|
lines = build_file_toc_lines(headings, FileTocConfig(min_heading=3, max_heading=6))
|
|
assert lines == [
|
|
"- [Sub](#sub)",
|
|
" - [Deeper](#deeper)",
|
|
]
|
|
|
|
def test_empty_headings(self):
|
|
"""Should return no entry lines without headings."""
|
|
assert build_file_toc_lines([], FileTocConfig()) == []
|
|
|
|
|
|
class TestGenerateFileToc:
|
|
"""Integration tests for generate_file_toc."""
|
|
|
|
def test_inserts_toc_below_h1(self, sample_doc):
|
|
"""Should insert the TOC directly below the H1."""
|
|
status = generate_file_toc(sample_doc, FileTocConfig())
|
|
assert status == "updated"
|
|
|
|
content = sample_doc.read_text(encoding="utf-8")
|
|
assert content == (
|
|
"# Guide\n"
|
|
"\n"
|
|
f"{file_toc_marker(FileTocConfig())}\n"
|
|
"\n"
|
|
"- [Section One](#section-one)\n"
|
|
" - [Sub One](#sub-one)\n"
|
|
"- [Section Two](#section-two)\n"
|
|
" - [Deep](#deep)\n"
|
|
"\n"
|
|
f"{FILE_TOC_END}\n"
|
|
"\n"
|
|
"intro text\n"
|
|
"\n"
|
|
"## Section One\n"
|
|
"\n"
|
|
"### Sub One\n"
|
|
"\n"
|
|
"## Section Two\n"
|
|
"\n"
|
|
"#### Deep\n"
|
|
)
|
|
|
|
def test_toc_block_blanks_around_entries(self, sample_doc):
|
|
"""Should blank-separate the entry list from the markers (MD032)."""
|
|
generate_file_toc(sample_doc, FileTocConfig())
|
|
lines = sample_doc.read_text(encoding="utf-8").splitlines()
|
|
start = lines.index(file_toc_marker(FileTocConfig()))
|
|
end = lines.index(FILE_TOC_END)
|
|
assert lines[start + 1] == ""
|
|
assert lines[end - 1] == ""
|
|
|
|
def test_h1_excluded(self, sample_doc):
|
|
"""Should never list the H1 in the TOC."""
|
|
generate_file_toc(sample_doc, FileTocConfig())
|
|
content = sample_doc.read_text(encoding="utf-8")
|
|
assert "- [Guide](#guide)" not in content
|
|
|
|
def test_max_heading_filter(self, sample_doc):
|
|
"""Should omit headings deeper than max_heading."""
|
|
generate_file_toc(sample_doc, FileTocConfig(max_heading=3))
|
|
content = sample_doc.read_text(encoding="utf-8")
|
|
assert "Sub One" in content
|
|
assert "- [Deep](#deep)" not in content
|
|
assert "#### Deep" in content
|
|
|
|
def test_fenced_headings_skipped(self, tmp_path):
|
|
"""Should ignore headings inside fenced code blocks."""
|
|
doc = tmp_path / "fenced.md"
|
|
doc.write_text(
|
|
"# Real\n\n```text\n## Fenced\n```\n\n## Real Sub\n",
|
|
encoding="utf-8",
|
|
)
|
|
generate_file_toc(doc, FileTocConfig())
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "- [Fenced](#fenced)" not in content
|
|
assert "- [Real Sub](#real-sub)" in content
|
|
|
|
def test_frontmatter_preserved(self, tmp_path):
|
|
"""Should keep frontmatter and find the H1 after it."""
|
|
doc = tmp_path / "front.md"
|
|
doc.write_text(
|
|
"---\nname: doc\nversion: 1.0.0\n# not a heading\n---\n# Title\n## A\n",
|
|
encoding="utf-8",
|
|
)
|
|
status = generate_file_toc(doc, FileTocConfig())
|
|
assert status == "updated"
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert content.startswith("---\nname: doc\nversion: 1.0.0\n# not a heading\n---\n")
|
|
assert "# not a heading\n" not in content[len("---\nname: doc\nversion: 1.0.0\n# not a heading\n---\n"):]
|
|
assert "- [A](#a)" in content
|
|
|
|
def test_regeneration_updates_in_place(self, sample_doc):
|
|
"""Should replace an existing TOC block instead of duplicating."""
|
|
generate_file_toc(sample_doc, FileTocConfig())
|
|
content = sample_doc.read_text(encoding="utf-8")
|
|
content = content.replace("## Section Two", "## Renamed Two")
|
|
sample_doc.write_text(content, encoding="utf-8")
|
|
|
|
status = generate_file_toc(sample_doc, FileTocConfig())
|
|
assert status == "updated"
|
|
final = sample_doc.read_text(encoding="utf-8")
|
|
assert final.count(FILE_TOC_START) == 1
|
|
assert final.count(FILE_TOC_END) == 1
|
|
assert "- [Renamed Two](#renamed-two)" in final
|
|
assert "- [Section Two](#section-two)" not in final
|
|
|
|
def test_second_run_is_unchanged(self, sample_doc):
|
|
"""Should report unchanged and not rewrite an up-to-date TOC."""
|
|
generate_file_toc(sample_doc, FileTocConfig())
|
|
before = sample_doc.read_text(encoding="utf-8")
|
|
assert generate_file_toc(sample_doc, FileTocConfig()) == "unchanged"
|
|
assert sample_doc.read_text(encoding="utf-8") == before
|
|
|
|
def test_no_h1_returns_status_without_write(self, tmp_path):
|
|
"""Should skip files without an H1 instead of writing a TOC."""
|
|
doc = tmp_path / "noh1.md"
|
|
doc.write_text("Just text\n\n## A\n", encoding="utf-8")
|
|
assert generate_file_toc(doc, FileTocConfig()) == "no-h1"
|
|
assert doc.read_text(encoding="utf-8") == "Just text\n\n## A\n"
|
|
|
|
def test_sectionize_numbers_headings_and_toc(self, tmp_path):
|
|
"""Should number headings in the file and the TOC entries."""
|
|
doc = tmp_path / "numbered.md"
|
|
doc.write_text("# Guide\n\n## Alpha\n\n## Beta\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(sectionize=True))
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "## 1. Alpha" in content
|
|
assert "## 2. Beta" in content
|
|
assert "- [1. Alpha](#1-alpha)" in content
|
|
assert "- [2. Beta](#2-beta)" in content
|
|
|
|
def test_sectionize_renumbers_existing_numbers(self, tmp_path):
|
|
"""Should update stale numbers when headings are inserted."""
|
|
doc = tmp_path / "renumber.md"
|
|
doc.write_text("# Guide\n\n## Alpha\n\n## Beta\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(sectionize=True))
|
|
content = doc.read_text(encoding="utf-8")
|
|
content = content.replace("## 1. Alpha", "## Zero\n\n## 1. Alpha")
|
|
sample_doc = doc
|
|
sample_doc.write_text(content, encoding="utf-8")
|
|
|
|
generate_file_toc(doc, FileTocConfig(sectionize=True))
|
|
final = doc.read_text(encoding="utf-8")
|
|
assert "## 1. Zero" in final
|
|
assert "## 2. Alpha" in final
|
|
assert "## 3. Beta" in final
|
|
assert "- [2. Alpha](#2-alpha)" in final
|
|
|
|
def test_sectionize_nested_levels(self, tmp_path):
|
|
"""Should number nested levels as 1.1., 1.2. and so on."""
|
|
doc = tmp_path / "nested.md"
|
|
doc.write_text("# Guide\n\n## A\n\n### A1\n\n### A2\n\n## B\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(sectionize=True))
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "### 1.1. A1" in content
|
|
assert "### 1.2. A2" in content
|
|
assert "- [1.2. A2](#12-a2)" in content
|
|
assert "## 2. B" in content
|
|
|
|
|
|
class TestGenerateFileTocs:
|
|
"""Tests for the bulk '*' mode."""
|
|
|
|
def test_processes_tree_and_reports(self, tmp_path):
|
|
"""Should generate TOCs recursively and report per-file statuses."""
|
|
(tmp_path / "a.md").write_text("# A\n## B\n", encoding="utf-8")
|
|
sub = tmp_path / "sub"
|
|
sub.mkdir()
|
|
(sub / "c.md").write_text("# C\n## D\n", encoding="utf-8")
|
|
|
|
results = generate_file_tocs(tmp_path, {})
|
|
|
|
statuses = {path.name: status for path, status in results}
|
|
assert statuses == {"a.md": "updated", "c.md": "updated"}
|
|
assert "- [B](#b)" in (tmp_path / "a.md").read_text(encoding="utf-8")
|
|
assert "- [D](#d)" in (sub / "c.md").read_text(encoding="utf-8")
|
|
|
|
def test_skips_readonly_zones(self, tmp_path):
|
|
"""Should never write into personal/ or raw/."""
|
|
personal = tmp_path / "personal"
|
|
personal.mkdir()
|
|
(personal / "notes.md").write_text("# N\n## S\n", encoding="utf-8")
|
|
raw = tmp_path / "raw"
|
|
raw.mkdir()
|
|
(raw / "src.md").write_text("# R\n## S\n", encoding="utf-8")
|
|
(tmp_path / "ok.md").write_text("# OK\n## S\n", encoding="utf-8")
|
|
|
|
results = generate_file_tocs(tmp_path, {})
|
|
|
|
statuses = {path.name: status for path, status in results}
|
|
assert statuses["notes.md"] == "read-only zone"
|
|
assert statuses["src.md"] == "read-only zone"
|
|
assert statuses["ok.md"] == "updated"
|
|
assert FILE_TOC_START not in (personal / "notes.md").read_text(encoding="utf-8")
|
|
|
|
def test_skips_ignore_files(self, tmp_path):
|
|
"""Should skip files matching ignore_files patterns."""
|
|
(tmp_path / "skipme.md").write_text("# S\n## T\n", encoding="utf-8")
|
|
(tmp_path / "keep.md").write_text("# K\n## T\n", encoding="utf-8")
|
|
settings = {"file": {"ignore_files": ["skip*"]}}
|
|
|
|
results = generate_file_tocs(tmp_path, settings)
|
|
|
|
statuses = {path.name: status for path, status in results}
|
|
assert statuses["skipme.md"] == "ignored"
|
|
assert statuses["keep.md"] == "updated"
|
|
assert FILE_TOC_START not in (tmp_path / "skipme.md").read_text(encoding="utf-8")
|
|
|
|
def test_skips_generated_and_hidden_files(self, tmp_path):
|
|
"""Should skip table_of_contents.md and hidden files."""
|
|
(tmp_path / TOC_NAME).write_text("# Table of Contents\n## X\n", encoding="utf-8")
|
|
hidden = tmp_path / ".hidden"
|
|
hidden.mkdir()
|
|
(hidden / "h.md").write_text("# H\n## X\n", encoding="utf-8")
|
|
|
|
results = generate_file_tocs(tmp_path, {})
|
|
|
|
statuses = {path.name: status for path, status in results}
|
|
assert statuses == {TOC_NAME: "generated toc file", "h.md": "hidden"}
|
|
|
|
|
|
class TestFindWikiRoot:
|
|
"""Tests for wiki root discovery via fiona-settings.json."""
|
|
|
|
def test_settings_in_start_dir(self, tmp_path):
|
|
"""Should return the start dir when it holds the settings file."""
|
|
(tmp_path / "fiona-settings.json").write_text("{}", encoding="utf-8")
|
|
assert find_wiki_root(tmp_path) == tmp_path.resolve()
|
|
|
|
def test_settings_in_subdir(self, tmp_path):
|
|
"""Should return the subdir holding the settings file."""
|
|
sub = tmp_path / "wiki"
|
|
sub.mkdir()
|
|
(sub / "fiona-settings.json").write_text("{}", encoding="utf-8")
|
|
assert find_wiki_root(tmp_path) == sub.resolve()
|
|
|
|
def test_no_settings_returns_start(self, tmp_path):
|
|
"""Should return the start dir when no settings file exists."""
|
|
assert find_wiki_root(tmp_path) == tmp_path.resolve()
|
|
|
|
|
|
class TestFileTocCli:
|
|
"""CLI tests for 'toc_generator file' (per-file TOC mode)."""
|
|
|
|
def test_cli_single_file(self, tmp_path, capsys, hermetic_settings):
|
|
"""Should write a TOC for an explicit file path."""
|
|
doc = tmp_path / "doc.md"
|
|
doc.write_text("# Title\n## Section\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", str(doc)]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "- [Section](#section)" in content
|
|
assert "wrote toc" in capsys.readouterr().out
|
|
|
|
def test_cli_star_processes_tree(self, tmp_path, monkeypatch, capsys, hermetic_settings):
|
|
"""Should process every md file under the current directory."""
|
|
(tmp_path / "a.md").write_text("# A\n## B\n", encoding="utf-8")
|
|
sub = tmp_path / "sub"
|
|
sub.mkdir()
|
|
(sub / "c.md").write_text("# C\n## D\n", encoding="utf-8")
|
|
monkeypatch.chdir(tmp_path)
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", "*"]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert "- [B](#b)" in (tmp_path / "a.md").read_text(encoding="utf-8")
|
|
assert "- [D](#d)" in (sub / "c.md").read_text(encoding="utf-8")
|
|
out = capsys.readouterr().out
|
|
assert "generated toc for 2 file(s)" in out
|
|
|
|
def test_cli_star_uses_wiki_root_settings(self, tmp_path, monkeypatch, capsys):
|
|
"""Should use the discovered wiki root and its settings."""
|
|
wiki = tmp_path / "wiki"
|
|
wiki.mkdir()
|
|
(wiki / "fiona-settings.json").write_text(
|
|
json.dumps({"toc_generator": {"file": {"max_heading": 2}}}),
|
|
encoding="utf-8",
|
|
)
|
|
(wiki / "doc.md").write_text("# T\n## Two\n### Three\n", encoding="utf-8")
|
|
monkeypatch.chdir(tmp_path)
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", "*"]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
content = (wiki / "doc.md").read_text(encoding="utf-8")
|
|
assert "- [Two](#two)" in content
|
|
assert "- [Three](#three)" not in content
|
|
|
|
def test_cli_missing_file_exits_with_error(self, tmp_path, capsys):
|
|
"""Should exit 1 with a clear error for a missing file."""
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", str(tmp_path / "missing.md")]
|
|
with pytest.raises(SystemExit) as excinfo:
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert excinfo.value.code == 1
|
|
assert "missing.md" in capsys.readouterr().err
|
|
|
|
def test_cli_non_md_file_exits_with_error(self, tmp_path, capsys):
|
|
"""Should exit 1 for a non-markdown file."""
|
|
doc = tmp_path / "notes.txt"
|
|
doc.write_text("text", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", str(doc)]
|
|
with pytest.raises(SystemExit) as excinfo:
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert excinfo.value.code == 1
|
|
assert "markdown" in capsys.readouterr().err
|
|
|
|
def test_cli_readonly_zone_exits_with_error(self, tmp_path, capsys):
|
|
"""Should exit 1 when the explicit file is in a read-only zone."""
|
|
personal = tmp_path / "personal"
|
|
personal.mkdir()
|
|
doc = personal / "notes.md"
|
|
doc.write_text("# N\n## S\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", str(doc)]
|
|
with pytest.raises(SystemExit) as excinfo:
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert excinfo.value.code == 1
|
|
assert "read-only" in capsys.readouterr().err
|
|
|
|
def test_cli_invalid_settings_exits_with_error(self, tmp_path, monkeypatch, capsys):
|
|
"""Should exit 1 with a clear stderr message on invalid settings."""
|
|
bad_settings = tmp_path / "fiona-settings.json"
|
|
bad_settings.write_text(
|
|
json.dumps({"toc_generator": {"file": {"min_heading": 1}}}),
|
|
encoding="utf-8",
|
|
)
|
|
monkeypatch.setattr(toc_generator, "DEFAULT_SETTINGS_FILE", bad_settings)
|
|
doc = tmp_path / "doc.md"
|
|
doc.write_text("# T\n## S\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", str(doc)]
|
|
with pytest.raises(SystemExit) as excinfo:
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert excinfo.value.code == 1
|
|
assert "min_heading" in capsys.readouterr().err
|
|
|
|
|
|
class TestPackagedFileTocSettings:
|
|
"""Tests for the packaged fiona-settings.json file section."""
|
|
|
|
def test_packaged_file_section_is_valid(self):
|
|
"""Should parse the packaged template's file section.
|
|
|
|
The template's file.sectionize value is user configuration, so
|
|
only the stable shape is asserted here.
|
|
"""
|
|
settings = load_toc_settings()
|
|
config = resolve_file_toc_config(settings, "some/page.md")
|
|
assert config.min_heading == 2
|
|
assert config.max_heading == 6
|
|
assert isinstance(config.sectionize, bool)
|
|
assert config.ignore_files == ()
|
|
|
|
def test_packaged_override_example(self):
|
|
"""Should apply the packaged rules.md override for matching paths."""
|
|
settings = load_toc_settings()
|
|
config = resolve_file_toc_config(settings, "sub/rules.md")
|
|
assert config.max_heading == 2
|
|
|
|
|
|
class TestFolderTocValidation:
|
|
"""Tests for folder-TOC target validation and reporting (SPEC 7.3.1.1)."""
|
|
|
|
def test_main_file_target_exits_with_error(self, tmp_path, capsys):
|
|
"""Should exit 1 with a hint when the target is a file, not a dir.
|
|
|
|
Reproduces: fiona-assistant librarian toc SPEC.md silently
|
|
did nothing.
|
|
"""
|
|
doc = tmp_path / "SPEC.md"
|
|
doc.write_text("# T\n## S\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", str(doc)]
|
|
with pytest.raises(SystemExit) as excinfo:
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert excinfo.value.code == 1
|
|
error = capsys.readouterr().err
|
|
assert "not a valid directory" in error
|
|
assert "toc file" in error
|
|
assert TOC_NAME not in [p.name for p in tmp_path.iterdir()]
|
|
|
|
def test_main_missing_directory_exits_with_error(self, tmp_path, capsys):
|
|
"""Should exit 1 with a clear error for a nonexistent directory."""
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", str(tmp_path / "missing")]
|
|
with pytest.raises(SystemExit) as excinfo:
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert excinfo.value.code == 1
|
|
assert "not a valid directory" in capsys.readouterr().err
|
|
|
|
def test_main_empty_directory_reports_no_files(self, tmp_path, capsys):
|
|
"""Should report when a folder has no markdown files."""
|
|
empty = tmp_path / "empty"
|
|
empty.mkdir()
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", str(empty)]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
out = capsys.readouterr().out
|
|
assert "no markdown files found" in out
|
|
assert not (empty / TOC_NAME).exists()
|
|
|
|
def test_main_recursive_empty_folders_not_printed(self, tmp_path, capsys):
|
|
"""Should log (not print) empty folders in recursive mode."""
|
|
(tmp_path / "docs").mkdir()
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", str(tmp_path), "-r"]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
out = capsys.readouterr().out
|
|
assert "no markdown files found" not in out
|
|
|
|
def test_main_logs_settings_file(self, tmp_path, caplog):
|
|
"""Should log the settings file used at INFO level."""
|
|
(tmp_path / "doc.md").write_text("# T\n## S\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
with caplog.at_level(logging.INFO):
|
|
sys.argv = ["toc_generator", str(tmp_path)]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert "settings" in caplog.text.lower()
|
|
|
|
def test_main_logs_written_toc(self, tmp_path, monkeypatch, caplog):
|
|
"""Should log each written TOC at DEBUG level."""
|
|
(tmp_path / "doc.md").write_text("# T\n## S\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
monkeypatch.setenv("LOG_LEVEL", "DEBUG")
|
|
with caplog.at_level(logging.DEBUG, logger="fiona.librarian"):
|
|
sys.argv = ["toc_generator", str(tmp_path)]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert "wrote" in caplog.text
|
|
|
|
|
|
class TestFileTocLogging:
|
|
"""Tests for logging in the per-file TOC CLI."""
|
|
|
|
def test_file_mode_logs_generated_toc(self, tmp_path, monkeypatch, caplog):
|
|
"""Should log each generated file TOC at DEBUG level."""
|
|
doc = tmp_path / "doc.md"
|
|
doc.write_text("# T\n## S\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
monkeypatch.setenv("LOG_LEVEL", "DEBUG")
|
|
with caplog.at_level(logging.DEBUG, logger="fiona.librarian"):
|
|
sys.argv = ["toc_generator", "file", str(doc)]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
assert str(doc) in caplog.text
|
|
|
|
|
|
class TestFindWikiRootArtifacts:
|
|
"""Tests for wiki root discovery skipping build artifacts."""
|
|
|
|
def _settings(self, folder):
|
|
folder.mkdir(parents=True)
|
|
(folder / "fiona-settings.json").write_text("{}", encoding="utf-8")
|
|
|
|
def test_build_dir_not_chosen(self, tmp_path):
|
|
"""Should skip build/ artifacts even though they sort first."""
|
|
self._settings(tmp_path / "build" / "lib" / "wiki")
|
|
self._settings(tmp_path / "src" / "wiki")
|
|
assert find_wiki_root(tmp_path) == (tmp_path / "src" / "wiki").resolve()
|
|
|
|
def test_build_dir_only_falls_back_to_start(self, tmp_path):
|
|
"""Should fall back to the start dir with only artifact candidates."""
|
|
self._settings(tmp_path / "build" / "lib" / "wiki")
|
|
assert find_wiki_root(tmp_path) == tmp_path.resolve()
|
|
|
|
def test_dist_dir_not_chosen(self, tmp_path):
|
|
"""Should skip dist/ artifacts."""
|
|
self._settings(tmp_path / "dist" / "wiki")
|
|
self._settings(tmp_path / "docs" / "wiki")
|
|
assert find_wiki_root(tmp_path) == (tmp_path / "docs" / "wiki").resolve()
|
|
|
|
def test_egg_info_dir_not_chosen(self, tmp_path):
|
|
"""Should skip *.egg-info/ artifacts."""
|
|
self._settings(tmp_path / "pkg.egg-info" / "wiki")
|
|
self._settings(tmp_path / "docs" / "wiki")
|
|
assert find_wiki_root(tmp_path) == (tmp_path / "docs" / "wiki").resolve()
|
|
|
|
def test_pycache_dir_not_chosen(self, tmp_path):
|
|
"""Should skip __pycache__/ artifacts."""
|
|
self._settings(tmp_path / "__pycache__" / "wiki")
|
|
self._settings(tmp_path / "docs" / "wiki")
|
|
assert find_wiki_root(tmp_path) == (tmp_path / "docs" / "wiki").resolve()
|
|
|
|
|
|
class TestTocMarker:
|
|
"""Tests for the toc-start marker recording its generation params."""
|
|
|
|
def test_marker_plain(self, sample_doc):
|
|
"""Should record the heading range for a plain TOC."""
|
|
generate_file_toc(sample_doc, FileTocConfig())
|
|
lines = sample_doc.read_text(encoding="utf-8").splitlines()
|
|
assert "<!-- toc-start: headings 2..6 -->" in lines
|
|
|
|
def test_marker_sectionized(self, tmp_path):
|
|
"""Should record sectionized state in the marker."""
|
|
doc = tmp_path / "numbered.md"
|
|
doc.write_text("# Guide\n\n## Alpha\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(sectionize=True))
|
|
lines = doc.read_text(encoding="utf-8").splitlines()
|
|
assert "<!-- toc-start: sectionized, headings 2..6 -->" in lines
|
|
|
|
def test_marker_custom_range(self, tmp_path):
|
|
"""Should record a custom min/max heading range."""
|
|
doc = tmp_path / "ranged.md"
|
|
doc.write_text("# Guide\n\n## Alpha\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(min_heading=3, max_heading=4))
|
|
lines = doc.read_text(encoding="utf-8").splitlines()
|
|
assert "<!-- toc-start: headings 3..4 -->" in lines
|
|
|
|
def test_old_style_marker_upgraded(self, tmp_path):
|
|
"""Should detect the old bare marker and upgrade it in place."""
|
|
doc = tmp_path / "legacy.md"
|
|
doc.write_text(
|
|
"# T\n\n<!-- toc-start -->\n\n- [Old](#old)\n\n<!-- toc-end -->\n\n## S\n",
|
|
encoding="utf-8",
|
|
)
|
|
status = generate_file_toc(doc, FileTocConfig())
|
|
assert status == "updated"
|
|
lines = doc.read_text(encoding="utf-8").splitlines()
|
|
starts = [line for line in lines if line.startswith("<!-- toc-start")]
|
|
assert starts == ["<!-- toc-start: headings 2..6 -->"]
|
|
assert "- [Old](#old)" not in lines
|
|
assert "- [S](#s)" in lines
|
|
|
|
def test_config_change_updates_marker(self, tmp_path):
|
|
"""Should keep the marker range when the settings range changes.
|
|
|
|
The marker params have priority over the settings (SPEC 7.3.1.2),
|
|
so a settings change alone leaves an existing TOC unchanged.
|
|
"""
|
|
doc = tmp_path / "doc.md"
|
|
doc.write_text("# T\n\n## S\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(max_heading=6))
|
|
assert generate_file_toc(doc, FileTocConfig(max_heading=2)) == "unchanged"
|
|
lines = doc.read_text(encoding="utf-8").splitlines()
|
|
assert "<!-- toc-start: headings 2..6 -->" in lines
|
|
|
|
|
|
class TestSectionizedFlag:
|
|
"""Tests for the --sectionized CLI flag."""
|
|
|
|
def test_cli_flag_forces_numbering(self, tmp_path, hermetic_settings, capsys):
|
|
"""Should force section numbering on regardless of settings."""
|
|
doc = tmp_path / "doc.md"
|
|
doc.write_text("# T\n\n## S\n\n## U\n", encoding="utf-8")
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", str(doc), "--sectionized"]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "## 1. S" in content
|
|
assert "## 2. U" in content
|
|
assert "- [1. S](#1-s)]" not in content
|
|
assert "- [1. S](#1-s)" in content
|
|
assert "<!-- toc-start: sectionized, headings 2..6 -->" in content
|
|
|
|
def test_cli_flag_with_star(self, tmp_path, hermetic_settings, monkeypatch):
|
|
"""Should apply the flag to every file in bulk mode."""
|
|
(tmp_path / "a.md").write_text("# A\n\n## B\n", encoding="utf-8")
|
|
monkeypatch.chdir(tmp_path)
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", "*", "--sectionized"]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
content = (tmp_path / "a.md").read_text(encoding="utf-8")
|
|
assert "## 1. B" in content
|
|
assert "- [1. B](#1-b)" in content
|
|
|
|
|
|
class TestMarkerPriority:
|
|
"""Tests for config resolution priority: marker > args > settings."""
|
|
|
|
def test_marker_params_parsed(self):
|
|
"""Should parse sectionized and range from a marker line."""
|
|
assert parse_file_toc_marker(
|
|
"<!-- toc-start: sectionized, headings 2..6 -->"
|
|
) == {"sectionized": True, "min_heading": 2, "max_heading": 6}
|
|
|
|
def test_marker_params_plain(self):
|
|
"""Should parse a plain marker as an empty param set."""
|
|
assert parse_file_toc_marker("<!-- toc-start: headings 2..6 -->") == {
|
|
"min_heading": 2,
|
|
"max_heading": 6,
|
|
}
|
|
|
|
def test_marker_params_bare_legacy(self):
|
|
"""Should parse a bare legacy marker to no params."""
|
|
assert parse_file_toc_marker("<!-- toc-start -->") == {}
|
|
|
|
def test_marker_params_non_marker_line(self):
|
|
"""Should return None for lines that are not markers."""
|
|
assert parse_file_toc_marker("## Heading") is None
|
|
assert parse_file_toc_marker("<!-- toc-end -->") is None
|
|
|
|
def test_sectionized_marker_sticky_over_settings(self, tmp_path):
|
|
"""Should keep numbering a sectionized TOC even with sectionize off."""
|
|
doc = tmp_path / "sticky.md"
|
|
doc.write_text(
|
|
"# T\n\n<!-- toc-start: sectionized, headings 2..6 -->\n\n"
|
|
"- [Old](#old)\n\n<!-- toc-end -->\n\n## Alpha\n",
|
|
encoding="utf-8",
|
|
)
|
|
generate_file_toc(doc, FileTocConfig(sectionize=False))
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "## 1. Alpha" in content
|
|
assert "- [1. Alpha](#1-alpha)]" not in content
|
|
assert "- [1. Alpha](#1-alpha)" in content
|
|
assert "<!-- toc-start: sectionized, headings 2..6 -->" in content
|
|
|
|
def test_marker_range_sticky_over_settings(self, tmp_path):
|
|
"""Should keep the marker's heading range over the settings range."""
|
|
doc = tmp_path / "ranged.md"
|
|
doc.write_text("# T\n\n## S\n\n### U\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(max_heading=6))
|
|
assert generate_file_toc(doc, FileTocConfig(max_heading=2)) == "unchanged"
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "- [U](#u)" in content
|
|
assert "<!-- toc-start: headings 2..6 -->" in content
|
|
|
|
def test_plain_marker_falls_through_to_settings(self, tmp_path):
|
|
"""Should apply settings when the marker records no sectionized flag."""
|
|
doc = tmp_path / "plain.md"
|
|
doc.write_text("# T\n\n## Alpha\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(sectionize=False))
|
|
generate_file_toc(doc, FileTocConfig(sectionize=True))
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "## 1. Alpha" in content
|
|
assert "<!-- toc-start: sectionized, headings 2..6 -->" in content
|
|
|
|
def test_bare_marker_falls_through_to_settings(self, tmp_path):
|
|
"""Should apply settings for a bare legacy marker."""
|
|
doc = tmp_path / "legacy.md"
|
|
doc.write_text(
|
|
"# T\n\n<!-- toc-start -->\n\n- [Old](#old)\n\n<!-- toc-end -->\n\n## S\n",
|
|
encoding="utf-8",
|
|
)
|
|
generate_file_toc(doc, FileTocConfig(sectionize=True))
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "## 1. S" in content
|
|
assert "<!-- toc-start: sectionized, headings 2..6 -->" in content
|
|
|
|
def test_invalid_marker_range_ignored(self, tmp_path):
|
|
"""Should warn and fall back to the settings range."""
|
|
doc = tmp_path / "badrange.md"
|
|
doc.write_text(
|
|
"# T\n\n<!-- toc-start: headings 9..12 -->\n\n- [Old](#old)\n\n"
|
|
"<!-- toc-end -->\n\n## S\n",
|
|
encoding="utf-8",
|
|
)
|
|
generate_file_toc(doc, FileTocConfig(max_heading=6))
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "- [S](#s)" in content
|
|
assert "<!-- toc-start: headings 2..6 -->" in content
|
|
|
|
def test_cli_sectionized_flag_overrides_plain_marker(self, tmp_path, hermetic_settings):
|
|
"""Should number a plain-marker TOC when --sectionized is passed."""
|
|
doc = tmp_path / "doc.md"
|
|
doc.write_text("# T\n\n## Alpha\n", encoding="utf-8")
|
|
generate_file_toc(doc, FileTocConfig(sectionize=False))
|
|
|
|
original_argv = sys.argv
|
|
try:
|
|
sys.argv = ["toc_generator", "file", str(doc), "--sectionized"]
|
|
main()
|
|
finally:
|
|
sys.argv = original_argv
|
|
|
|
content = doc.read_text(encoding="utf-8")
|
|
assert "## 1. Alpha" in content
|
|
assert "<!-- toc-start: sectionized, headings 2..6 -->" in content
|