Files
fiona-assistant/tests/test_toc_generator.py
T

1697 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 "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()
# TOC should start with frontmatter delimiters
assert content.startswith("---"), "TOC should start with frontmatter delimiter"
assert "---" in content[1:100], "TOC should have closing frontmatter delimiter"
# TOC should have frontmatter fields
assert "title:" in content[:200], "TOC should have title in frontmatter"
assert "created:" in content[:300] or "date:" in content[:300], "TOC should have date field in frontmatter"
assert "type:" in content[:300], "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