refkit 0.0.2__tar.gz → 0.0.3__tar.gz

{refkit-0.0.2 → refkit-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refkit
-Version: 0.0.2
+Version: 0.0.3
 Summary: Fast Python citation parsing, rendering, and BibTeX editing backed by Rust
 Author-email: Péter Ferenc Gyarmati <dev.petergy@gmail.com>
 License-Expression: Apache-2.0
@@ -17,12 +17,12 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Rust
 Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.11
-Requires-Dist: refkit-core==0.0.2
+Requires-Dist: refkit-core==0.0.3
 Description-Content-Type: text/markdown
 
 # refkit
 
-`refkit` reads BibTeX, BibLaTeX, and Hayagriva YAML, renders CSL citations, and edits raw BibTeX documents from Python.
+`refkit` reads BibTeX, BibLaTeX, and Hayagriva YAML, renders CSL citations, formats BibTeX, and edits raw BibTeX documents from Python.
 
 ## Install
 
@@ -31,9 +31,9 @@ pip install refkit
 ```
 
 `refkit` is pure Python and depends on the exact matching `refkit-core` release.
-`refkit-core` contains the Rust/PyO3 extension as `refkit_core._refkit_core`, including PyEmscripten wheels for the Python 3.14 Pyodide runtime.
+`refkit-core` contains the Rust/PyO3 extension as `refkit_core._refkit_core`, including PyEmscripten wheels for Pyodide.
 
-`refkit` supports CPython 3.11 through 3.14. Native wheels from `refkit-core` use the Python 3.11 stable ABI.
+The supported Python versions and native wheel ABI are declared in package metadata and release workflows.
 
 ## Render A Citation
 
@@ -95,6 +95,53 @@ rk.full_bibliography("refs.bib", style="chicago-author-date").html
 
 Use `Library.parse_bibtex`, `Library.parse_yaml`, and `Document` when the bibliography source is already in memory or when several citations share the same library and style.
 
+## Format BibTeX
+
+`tidy_bibtex` formats BibTeX text and returns `TidyResult` with the formatted source, warnings, and entry count.
+
+```python
+import refkit as rk
+
+result = rk.tidy_bibtex(
+    """
+@ARTICLE {doe2024,
+  pages={6-13},
+  year={2024},}
+"""
+)
+
+print(result.bibtex)
+print(result.count)
+```
+
+Use `TidyOptions` for formatting choices:
+
+```python
+options = rk.TidyOptions(sort_fields=True, wrap=88)
+result = rk.tidy_bibtex(source, options=options)
+```
+
+Warnings are structured objects:
+
+```python
+for warning in result.warnings:
+    print(warning.code, warning.rule, warning.message)
+```
+
+Raw edit flows can render the current document state before formatting:
+
+```python
+raw = rk.BibDocument.read("refs.bib")
+raw.entries["doe2024"].fields["title"].value = "Corrected title"
+result = raw.tidy(options=rk.TidyOptions(sort_fields=True))
+```
+
+Use `tidy_file` when the input is on disk. It writes a file when `output` is supplied.
+
+```python
+rk.tidy_file("refs.bib", output="refs.tidy.bib")
+```
+
 ## Capabilities
 
 | Capability | Python surface |
@@ -104,6 +151,7 @@ Use `Library.parse_bibtex`, `Library.parse_yaml`, and `Document` when the biblio
 | Render bibliographies | `Document.cited_bibliography`, `Document.full_bibliography`, `full_bibliography` |
 | Load styles and locales | `Style.load`, `Style.from_path`, `Style.from_xml`, `Locale.load` |
 | Inspect entries | mapping access, `keys`, `get`, `get_many`, `select`, `project`, `to_dicts` |
+| Format BibTeX | `tidy_bibtex`, `tidy_file`, `TidyOptions`, `TidyResult` |
 | Edit raw BibTeX | `BibDocument.read`, `BibDocument.parse`, field assignment, `write` |
 | Inspect rendered output | `Rendered.text`, `Rendered.html`, `Rendered.tree` |
 
@@ -167,7 +215,7 @@ for entry in library.select("article > periodical[volume]"):
 
 ## Edit Raw BibTeX
 
-`BibDocument` preserves the raw `.bib` structure that normalized rendering does not need: comments, preambles, string definitions, failed blocks, order, and source spans.
+`BibDocument` preserves raw `.bib` comments, preambles, string definitions, failed blocks, order, and source spans.
 
 ```python
 raw = rk.BibDocument.read("refs.bib")
@@ -229,19 +277,15 @@ out = df.select(
 ## Development
 
 ```bash
-uv sync --all-packages --group dev
+uv sync --locked --all-packages --group dev
 (cd packages/refkit-core && uv run maturin develop)
-uv run pytest packages/refkit/tests --no-cov
+uv run --locked --all-packages --group dev python -m pytest packages/refkit/tests --no-cov
 ```
 
-The workspace also provides:
+Run every workspace gate from the repository root:
 
 ```bash
-make lint
-make typecheck
-make test
-make rust
-make build
+make check
 ```
 
 ## License

{refkit-0.0.2 → refkit-0.0.3}/README.md

@@ -1,6 +1,6 @@
 # refkit
 
-`refkit` reads BibTeX, BibLaTeX, and Hayagriva YAML, renders CSL citations, and edits raw BibTeX documents from Python.
+`refkit` reads BibTeX, BibLaTeX, and Hayagriva YAML, renders CSL citations, formats BibTeX, and edits raw BibTeX documents from Python.
 
 ## Install
 
@@ -9,9 +9,9 @@ pip install refkit
 ```
 
 `refkit` is pure Python and depends on the exact matching `refkit-core` release.
-`refkit-core` contains the Rust/PyO3 extension as `refkit_core._refkit_core`, including PyEmscripten wheels for the Python 3.14 Pyodide runtime.
+`refkit-core` contains the Rust/PyO3 extension as `refkit_core._refkit_core`, including PyEmscripten wheels for Pyodide.
 
-`refkit` supports CPython 3.11 through 3.14. Native wheels from `refkit-core` use the Python 3.11 stable ABI.
+The supported Python versions and native wheel ABI are declared in package metadata and release workflows.
 
 ## Render A Citation
 
@@ -73,6 +73,53 @@ rk.full_bibliography("refs.bib", style="chicago-author-date").html
 
 Use `Library.parse_bibtex`, `Library.parse_yaml`, and `Document` when the bibliography source is already in memory or when several citations share the same library and style.
 
+## Format BibTeX
+
+`tidy_bibtex` formats BibTeX text and returns `TidyResult` with the formatted source, warnings, and entry count.
+
+```python
+import refkit as rk
+
+result = rk.tidy_bibtex(
+    """
+@ARTICLE {doe2024,
+  pages={6-13},
+  year={2024},}
+"""
+)
+
+print(result.bibtex)
+print(result.count)
+```
+
+Use `TidyOptions` for formatting choices:
+
+```python
+options = rk.TidyOptions(sort_fields=True, wrap=88)
+result = rk.tidy_bibtex(source, options=options)
+```
+
+Warnings are structured objects:
+
+```python
+for warning in result.warnings:
+    print(warning.code, warning.rule, warning.message)
+```
+
+Raw edit flows can render the current document state before formatting:
+
+```python
+raw = rk.BibDocument.read("refs.bib")
+raw.entries["doe2024"].fields["title"].value = "Corrected title"
+result = raw.tidy(options=rk.TidyOptions(sort_fields=True))
+```
+
+Use `tidy_file` when the input is on disk. It writes a file when `output` is supplied.
+
+```python
+rk.tidy_file("refs.bib", output="refs.tidy.bib")
+```
+
 ## Capabilities
 
 | Capability | Python surface |
@@ -82,6 +129,7 @@ Use `Library.parse_bibtex`, `Library.parse_yaml`, and `Document` when the biblio
 | Render bibliographies | `Document.cited_bibliography`, `Document.full_bibliography`, `full_bibliography` |
 | Load styles and locales | `Style.load`, `Style.from_path`, `Style.from_xml`, `Locale.load` |
 | Inspect entries | mapping access, `keys`, `get`, `get_many`, `select`, `project`, `to_dicts` |
+| Format BibTeX | `tidy_bibtex`, `tidy_file`, `TidyOptions`, `TidyResult` |
 | Edit raw BibTeX | `BibDocument.read`, `BibDocument.parse`, field assignment, `write` |
 | Inspect rendered output | `Rendered.text`, `Rendered.html`, `Rendered.tree` |
 
@@ -145,7 +193,7 @@ for entry in library.select("article > periodical[volume]"):
 
 ## Edit Raw BibTeX
 
-`BibDocument` preserves the raw `.bib` structure that normalized rendering does not need: comments, preambles, string definitions, failed blocks, order, and source spans.
+`BibDocument` preserves raw `.bib` comments, preambles, string definitions, failed blocks, order, and source spans.
 
 ```python
 raw = rk.BibDocument.read("refs.bib")
@@ -207,19 +255,15 @@ out = df.select(
 ## Development
 
 ```bash
-uv sync --all-packages --group dev
+uv sync --locked --all-packages --group dev
 (cd packages/refkit-core && uv run maturin develop)
-uv run pytest packages/refkit/tests --no-cov
+uv run --locked --all-packages --group dev python -m pytest packages/refkit/tests --no-cov
 ```
 
-The workspace also provides:
+Run every workspace gate from the repository root:
 
 ```bash
-make lint
-make typecheck
-make test
-make rust
-make build
+make check
 ```
 
 ## License

{refkit-0.0.2 → refkit-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "refkit"
-version = "0.0.2"
+version = "0.0.3"
 description = "Fast Python citation parsing, rendering, and BibTeX editing backed by Rust"
 readme = "README.md"
 license = "Apache-2.0"
@@ -22,7 +22,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "refkit-core==0.0.2",
+    "refkit-core==0.0.3",
 ]
 
 [build-system]

{refkit-0.0.2 → refkit-0.0.3}/src/refkit/__init__.py

@@ -4,17 +4,17 @@ from __future__ import annotations
 
 from importlib.metadata import version as _metadata_version
 from os import PathLike
+from pathlib import Path
 
 import refkit_core as _core
 
-_COMPATIBLE_REFKIT_CORE_VERSION = "0.0.2"
 __version__ = _metadata_version("refkit")
 
 
 def check_refkit_core_version() -> bool:
     """Return whether the installed `refkit-core` version matches `refkit`."""
 
-    return _core.__version__ == _COMPATIBLE_REFKIT_CORE_VERSION
+    return _core.__version__ == __version__
 
 
 def _ensure_refkit_core_version() -> None:
@@ -22,7 +22,7 @@ def _ensure_refkit_core_version() -> None:
         return
     raise SystemError(
         f"The installed refkit-core version ({_core.__version__}) is incompatible "
-        f"with refkit {__version__}, which requires {_COMPATIBLE_REFKIT_CORE_VERSION}. "
+        f"with refkit {__version__}. "
         "Install refkit and refkit-core from the same release."
     )
 
@@ -46,6 +46,11 @@ RefkitError = _core.RefkitError
 Rendered = _core.Rendered
 RenderedDocument = _core.RenderedDocument
 Style = _core.Style
+TidyError = _core.TidyError
+TidyOptions = _core.TidyOptions
+TidyResult = _core.TidyResult
+TidySyntaxError = _core.TidySyntaxError
+TidyWarning = _core.TidyWarning
 build_info = _core.build_info
 build_mode = _core.build_mode
 
@@ -67,15 +72,46 @@ __all__ = [
     "Rendered",
     "RenderedDocument",
     "Style",
+    "TidyError",
+    "TidyOptions",
+    "TidyResult",
+    "TidySyntaxError",
+    "TidyWarning",
     "build_info",
     "build_mode",
     "cite",
     "full_bibliography",
+    "tidy_bibtex",
+    "tidy_file",
     "check_refkit_core_version",
     "__version__",
 ]
 
 
+def tidy_bibtex(
+    source: str,
+    *,
+    options: TidyOptions | None = None,
+) -> TidyResult:
+    """Format BibTeX text and return the formatted source plus warnings."""
+
+    return _core.tidy_bibtex(source, options=options)
+
+
+def tidy_file(
+    path: str | PathLike[str],
+    *,
+    output: str | PathLike[str] | None = None,
+    options: TidyOptions | None = None,
+) -> TidyResult:
+    """Read a BibTeX file, format it, and write the result when `output` is set."""
+
+    result = BibDocument.read(path).tidy(options=options)
+    if output is not None:
+        Path(output).write_text(result.bibtex, encoding="utf-8")
+    return result
+
+
 def cite(
     source: str | PathLike[str],
     citation: str | Cite | CitationGroup,

{refkit-0.0.2 → refkit-0.0.3}/src/refkit/__init__.pyi

@@ -18,6 +18,11 @@ from refkit_core import (
     Rendered,
     RenderedDocument,
     Style,
+    TidyError,
+    TidyOptions,
+    TidyResult,
+    TidySyntaxError,
+    TidyWarning,
     build_info,
     build_mode,
 )
@@ -40,10 +45,17 @@ __all__ = [
     "Rendered",
     "RenderedDocument",
     "Style",
+    "TidyError",
+    "TidyOptions",
+    "TidyResult",
+    "TidySyntaxError",
+    "TidyWarning",
     "build_info",
     "build_mode",
     "cite",
     "full_bibliography",
+    "tidy_bibtex",
+    "tidy_file",
     "check_refkit_core_version",
     "__version__",
 ]
@@ -51,6 +63,17 @@ __all__ = [
 __version__: str
 
 def check_refkit_core_version() -> bool: ...
+def tidy_bibtex(
+    source: str,
+    *,
+    options: TidyOptions | None = None,
+) -> TidyResult: ...
+def tidy_file(
+    path: str | PathLike[str],
+    *,
+    output: str | PathLike[str] | None = None,
+    options: TidyOptions | None = None,
+) -> TidyResult: ...
 def cite(
     source: str | PathLike[str],
     citation: str | Cite | CitationGroup,

refkit-0.0.3/tests/test_properties.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import string
+
+import hypothesis.strategies as st
+import pytest
+from hypothesis import given, settings
+
+import refkit as rk
+
+KEYS = st.from_regex(r"[A-Za-z][A-Za-z0-9_-]{0,15}", fullmatch=True)
+TEXT = st.text(alphabet=string.ascii_letters + string.digits + " ", min_size=1, max_size=32)
+YEARS = st.integers(min_value=1000, max_value=9999)
+
+
+def _entry(key: str, title: str, year: int) -> str:
+    return f"@article{{{key}, title={{{title}}}, year={{{year}}}}}"
+
+
+@given(key=KEYS, title=TEXT, year=YEARS)
+@settings(max_examples=75, deadline=None)
+def test_tidy_bibtex_is_idempotent_for_valid_entries(key: str, title: str, year: int) -> None:
+    first = rk.tidy_bibtex(_entry(key, title, year)).bibtex
+    second = rk.tidy_bibtex(first).bibtex
+
+    assert second == first
+    assert rk.Library.parse_bibtex(first).keys() == [key]
+
+
+@given(key=KEYS, title=TEXT, replacement=TEXT, year=YEARS)
+@settings(max_examples=50, deadline=None)
+def test_raw_title_edits_survive_serialization(
+    key: str,
+    title: str,
+    replacement: str,
+    year: int,
+) -> None:
+    document = rk.BibDocument.parse(_entry(key, title, year))
+    document.entries[key].fields["title"].value = replacement
+    serialized = document.to_bibtex()
+
+    assert replacement in serialized
+    assert rk.Library.parse_bibtex(serialized).keys() == [key]
+
+
+@given(key=KEYS, title=TEXT)
+@settings(max_examples=50, deadline=None)
+def test_default_parser_rejects_unclosed_entries(key: str, title: str) -> None:
+    with pytest.raises(rk.RefkitError, match="parse error"):
+        rk.Library.parse_bibtex(f"@article{{{key}, title={{{title}")

{refkit-0.0.2 → refkit-0.0.3}/tests/test_public_api.py

@@ -200,10 +200,11 @@ def test_real_bibliography_fixture_parses_inspects_and_renders() -> None:
     assert len(library) == 12
     assert library.diagnostics == []
     assert len(raw.entries) == 12
-    assert raw.comments[0].startswith("% Real BibTeX subset")
     title = rows["DeepResearchGym"]["title"]
-    assert isinstance(title, str)
-    assert title.startswith("DeepResearchGym")
+    assert (
+        title == "DeepResearchGym: A Free, Transparent, and Reproducible Evaluation Sandbox "
+        "for Deep Research"
+    )
     assert rows["DeepResearchGym"]["doi"] == "10.48550/ARXIV.2505.19253"
     assert rows["ijcai2019p684"]["volume"] is None
     assert _render_one(doc, "ijcai2019p684").text == "(Chen et al., 2019)"
@@ -253,12 +254,11 @@ def test_library_parse_accepts_source_strings_and_mapping_helpers() -> None:
 """,
     )
 
-    assert library
-    assert not library.is_empty()
     assert library.keys() == ["inline"]
-    entry = library.get("inline")
-    assert entry is not None
+    entry = cast(rk.Entry, library.get("inline"))
+    assert entry.key == "inline"
     assert entry.title == "Inline Source"
+    assert library["inline"].title == "Inline Source"
     assert library.get("missing") is None
     assert [entry.key for entry in library.get_many(["inline"])] == ["inline"]
     assert library.get_many(["inline"])[0].title == "Inline Source"
@@ -365,14 +365,17 @@ def test_refkit_import_reports_runtime_core_metadata() -> None:
 def test_refkit_import_rejects_mismatched_core_version(monkeypatch: pytest.MonkeyPatch) -> None:
     required_core_version = metadata.version("refkit-core")
     mismatched_core = ModuleType("refkit_core")
-    cast(Any, mismatched_core).__version__ = f"{required_core_version}.mismatch"
+    mismatched_version = f"{required_core_version}.mismatch"
+    cast(Any, mismatched_core).__version__ = mismatched_version
 
     monkeypatch.setitem(sys.modules, "refkit_core", mismatched_core)
     monkeypatch.delitem(sys.modules, "refkit")
     monkeypatch.syspath_prepend(str(ROOT / "src"))
     try:
-        with pytest.raises(SystemError, match=f"requires {required_core_version}"):
+        with pytest.raises(SystemError) as raised:
             importlib.import_module("refkit")
+        assert required_core_version in str(raised.value)
+        assert mismatched_version in str(raised.value)
     finally:
         sys.modules["refkit"] = rk
 
@@ -436,11 +439,16 @@ def test_bibliography_text_and_tree_include_second_field_labels() -> None:
     entry = cast(dict[str, Any], rendered.tree[0])
     first_field = cast(dict[str, Any], entry["first_field"])
 
-    assert rendered.text.startswith("[1]")
+    assert rendered.text == (
+        "[1] J. Doe, “Refkit for Bibliographies,” Journal of Citation Systems, "
+        "vol. 12, pp. 1–20, 2024, doi: 10.1234/refkit.2024."
+    )
     assert entry["kind"] == "bibliography-entry"
     assert first_field["kind"] == "Element"
     assert first_field["meta"] == "CitationNumber"
-    assert any(node.get("text") == "[1]" for node in _tree_nodes(first_field))
+    assert [
+        node.get("text") for node in _tree_nodes(first_field) if node.get("kind") == "Text"
+    ] == ["[1]"]
 
 
 def test_rendered_tree_exposes_documented_structured_keys() -> None:
@@ -454,7 +462,8 @@ def test_rendered_tree_exposes_documented_structured_keys() -> None:
     assert "children" in citation_tree[0]
     assert bibliography_tree[0]["kind"] == "bibliography-entry"
     assert bibliography_tree[0]["key"] == "doe2024"
-    assert bibliography_tree[0]["first_field"] is not None
+    first_field = cast(dict[str, Any], bibliography_tree[0]["first_field"])
+    assert first_field["kind"] == "Element"
     assert bibliography_tree[0]["children"][0]["kind"] == "Element"
 
 
@@ -485,8 +494,7 @@ def test_library_reads_yaml_and_selects_parent_periodical() -> None:
     library = rk.Library.read(FIXTURES / "parent.yaml")
     matches = library.select("article > periodical[volume]")
 
-    assert len(matches) == 1
-    assert matches[0].key == "doe2024"
+    assert [entry.key for entry in matches] == ["doe2024"]
     assert matches[0].title == "Refkit for Bibliographies"
     assert matches[0].parents[0].title == "Journal of Citation Systems"
 
@@ -574,7 +582,7 @@ def test_style_and_locale_loaders_cover_supported_sources() -> None:
     assert bundled.title == "APA Style 7th edition"
     assert from_xml.id == "xml"
     assert from_xml.title == "Refkit Note Fixture"
-    assert from_path.id.endswith("refkit-note.csl")
+    assert Path(from_path.id) == FIXTURES / "refkit-note.csl"
     assert from_path.title == "Refkit Note Fixture"
     assert locale.code == "en-US"
     assert "Doe" in _render_one(document, "doe2024").text
@@ -703,7 +711,8 @@ def test_library_non_strict_recovers_entry_after_malformed_at_line(tmp_path: Pat
     library = rk.Library.read(source, recovery="report")
 
     assert library.keys() == ["valid"]
-    assert "ignored malformed BibTeX block" in library.diagnostics[0]
+    assert library.diagnostics
+    assert "ignored" in library.diagnostics[0]
 
 
 def test_library_non_strict_drops_closed_malformed_entries(tmp_path: Path) -> None:
@@ -748,7 +757,8 @@ def test_library_non_strict_drops_missing_separator_after_bare_value(tmp_path: P
     library = rk.Library.read(source, recovery="report")
 
     assert library.keys() == ["valid"]
-    assert "ignored malformed BibTeX block" in library.diagnostics[0]
+    assert library.diagnostics
+    assert "ignored" in library.diagnostics[0]
 
 
 def test_library_non_strict_drops_missing_field_values(tmp_path: Path) -> None:
@@ -770,7 +780,8 @@ def test_library_non_strict_drops_missing_field_values(tmp_path: Path) -> None:
     library = rk.Library.read(source, recovery="report")
 
     assert library.keys() == ["valid"]
-    assert "ignored malformed BibTeX block" in library.diagnostics[0]
+    assert library.diagnostics
+    assert "ignored" in library.diagnostics[0]
 
 
 def test_library_non_strict_drops_entries_missing_key_comma(tmp_path: Path) -> None:
@@ -792,7 +803,8 @@ def test_library_non_strict_drops_entries_missing_key_comma(tmp_path: Path) -> N
     library = rk.Library.read(source, recovery="report")
 
     assert library.keys() == ["valid"]
-    assert "ignored malformed BibTeX block" in library.diagnostics[0]
+    assert library.diagnostics
+    assert "ignored" in library.diagnostics[0]
 
 
 def test_library_non_strict_drops_malformed_field_identifiers(tmp_path: Path) -> None:
@@ -814,7 +826,8 @@ def test_library_non_strict_drops_malformed_field_identifiers(tmp_path: Path) ->
     library = rk.Library.read(source, recovery="report")
 
     assert library.keys() == ["valid"]
-    assert "ignored malformed BibTeX block" in library.diagnostics[0]
+    assert library.diagnostics
+    assert "ignored" in library.diagnostics[0]
 
 
 def test_library_non_strict_drops_malformed_unsafe_bare_values(tmp_path: Path) -> None:
@@ -857,8 +870,11 @@ def test_library_non_strict_drops_malformed_string_definitions(tmp_path: Path) -
     library = rk.Library.read(source, recovery="report")
 
     assert library.keys() == ["valid"]
-    assert len(library.diagnostics) == 3
-    assert all("ignored malformed BibTeX block" in item for item in library.diagnostics)
+    assert len(library.diagnostics) == 4
+    assert library.diagnostics[0].startswith("syntax recovery could not pre-filter BibTeX entries")
+    assert [
+        diagnostic.startswith("ignored string definition") for diagnostic in library.diagnostics[1:]
+    ] == [True, True, True]
 
 
 def test_library_recovery_ignores_invalid_typed_fields() -> None:
@@ -1316,16 +1332,13 @@ def test_raw_bib_document_edits_duplicate_occurrences_without_losing_raw_blocks(
 
     raw.write(output)
 
-    text = output.read_text(encoding="utf-8")
-    assert "% duplicate raw fixture" in text
-    assert '@preamble{"Duplicate fixture"}' in text
-    assert "@string{j = {Journal of Duplicate Contracts}}" in text
-    assert "raw prose outside entries" in text
-    assert "@broken{bad" in text
-    assert "Corrected Second Field" in text
-    assert "Corrected Duplicate Entry" in text
-
     written = rk.BibDocument.read(output)
+    assert written.comments == ["% duplicate raw fixture\n"]
+    assert written.preamble == "Duplicate fixture"
+    assert written.strings["j"] == "Journal of Duplicate Contracts"
+    assert [block["raw"] for block in written.blocks if block["kind"] == "other"] == [
+        "raw prose outside entries\n\n"
+    ]
     written_first, written_second = written.entries.get_all("dup")
     assert [field.value for field in written_first.fields.get_all("title")] == [
         "First Title",
@@ -1333,7 +1346,7 @@ def test_raw_bib_document_edits_duplicate_occurrences_without_losing_raw_blocks(
     ]
     assert written_second.fields["title"].value == "Corrected Duplicate Entry"
     assert written.entries["later"].fields["title"].value == "Later Entry"
-    assert written.failed_blocks[0]["raw"].startswith("@broken{bad")
+    assert written.failed_blocks[0]["raw"] == "@broken{bad,\n  title = {No close}\n\n"
 
 
 def test_raw_bib_document_preserves_blocks_and_writes_field_edit(tmp_path: Path) -> None:
@@ -1341,7 +1354,7 @@ def test_raw_bib_document_preserves_blocks_and_writes_field_edit(tmp_path: Path)
     blocks = raw.blocks
     source = (FIXTURES / "raw.bib").read_text(encoding="utf-8")
 
-    assert raw.comments[0].startswith("% library comment")
+    assert raw.comments == ["% library comment\n", "% trailing comment\n"]
     assert raw.preamble == "BibTeX preamble"
     assert raw.strings["jcs"] == "Journal of Citation Systems"
     assert blocks[0]["kind"] == "comment"
@@ -1358,14 +1371,11 @@ def test_raw_bib_document_preserves_blocks_and_writes_field_edit(tmp_path: Path)
     output = tmp_path / "updated.bib"
     raw.write(output)
 
-    text = output.read_text()
-    assert "% library comment" in text
-    assert "@preamble" in text
-    assert "@string" in text
-    assert "@broken" in text
-    assert "Corrected title" in text
-    assert "journal = jcs" in text
     written = rk.BibDocument.read(output)
+    assert written.comments[:2] == ["% library comment\n", "% trailing comment\n"]
+    assert written.preamble == "BibTeX preamble"
+    assert written.strings["jcs"] == "Journal of Citation Systems"
+    assert written.failed_blocks[0]["raw"] == "@broken{missing,\n  title = {No close}\n"
     assert written.entries["doe2024"].fields["title"].value == "Corrected title"
     assert written.entries["doe2024"].fields["journal"].value == "jcs"
 
@@ -1373,28 +1383,33 @@ def test_raw_bib_document_preserves_blocks_and_writes_field_edit(tmp_path: Path)
 def test_raw_bib_document_preserves_typst_biblatex_blocks(tmp_path: Path) -> None:
     raw = rk.BibDocument.read(FIXTURES / "typst-raw.bib")
 
-    assert raw.comments[0].startswith("@comment")
-    assert any(comment.startswith("% Comments before") for comment in raw.comments)
+    assert raw.comments == [
+        "@comment{thisdoesntmatter,\n  does = {not matter}\n}",
+        "% Comments before the entry work\n",
+        "% A comment after the entry\n",
+    ]
     assert raw.strings["benchjournal"] == "Journal of Citation Benchmarks"
     assert raw.preamble == '"Reference " # "fixture"'
     assert raw.entries.unique_keys() == ["fischer2022equivalence", "roes2003belief"]
     assert raw.entries["roes2003belief"].span[0] < raw.entries["roes2003belief"].span[1]
     assert raw.failed_blocks[0]["kind"] == "failed"
-    assert "field author is missing '='" in raw.failed_blocks[0]["error"]
+    assert raw.failed_blocks[0]["error"]
 
     raw.entries["roes2003belief"].fields["title"].value = "Edited belief title"
     output = tmp_path / "typst-raw-out.bib"
     raw.write(output)
 
-    text = output.read_text(encoding="utf-8")
-    assert "@comment{thisdoesntmatter" in text
-    assert "% Comments before the entry work" in text
-    assert "@string{benchjournal" in text
-    assert '@preamble{"Reference " # "fixture"}' in text
-    assert "Edited belief title" in text
-    assert "@inproceedings{conigliocorbalan" in text
-    assert "author    {Marcelo Coniglio and Maria Corbalan}" in text
     written = rk.BibDocument.read(output)
+    assert written.comments == raw.comments
+    assert written.strings["benchjournal"] == "Journal of Citation Benchmarks"
+    assert written.preamble == '"Reference " # "fixture"'
+    assert written.failed_blocks[0]["raw"] == (
+        "@inproceedings{conigliocorbalan,\n"
+        "  author    {Marcelo Coniglio and Maria Corbalan},\n"
+        "  title     = {Sequent Calculi for Nonsense Logics},\n"
+        "  year      = {2012}\n"
+        "}"
+    )
     assert written.entries["roes2003belief"].fields["title"].value == "Edited belief title"
 
 
@@ -1412,35 +1427,26 @@ def test_raw_bib_document_parse_accepts_source_strings_and_mapping_helpers(
     )
 
     assert raw.comments == ["% inline comment\n"]
-    assert raw.entries
-    assert not raw.entries.is_empty()
-    assert "inline" in raw.entries
-    assert "missing" not in raw.entries
-    entry = raw.entries.get_unique("inline")
-    assert entry is not None
+    assert raw.entries.unique_keys() == ["inline"]
+    entry = raw.entries["inline"]
     assert entry.key == "inline"
     assert raw.entries.get_unique("missing") is None
     assert [entry.key for entry in raw.entries.occurrences()] == ["inline"]
     assert [entry.key for entry in raw.entries.get_all("inline")] == ["inline"]
-    assert raw.entries["inline"].fields
-    assert not raw.entries["inline"].fields.is_empty()
-    title = raw.entries["inline"].fields.get_unique("title")
-    assert title is not None
+    assert entry.fields.unique_keys() == ["title"]
+    title = entry.fields["title"]
     assert title.name == "title"
     assert title.value == "Inline Raw"
-    assert [field.name for field in raw.entries["inline"].fields.occurrences()] == ["title"]
-    assert [field.value for field in raw.entries["inline"].fields.get_all("title")] == [
-        "Inline Raw"
-    ]
-    assert "title" in raw.entries["inline"].fields
-    assert "missing" not in raw.entries["inline"].fields
-    assert raw.entries["inline"].fields.get_unique("missing") is None
+    assert [field.name for field in entry.fields.occurrences()] == ["title"]
+    assert [field.value for field in entry.fields.get_all("title")] == ["Inline Raw"]
+    assert entry.fields.get_unique("missing") is None
     assert raw.failed_blocks
 
     output = tmp_path / "inline.bib"
     raw.write(output)
 
-    assert "@article{inline" in output.read_text(encoding="utf-8")
+    written = rk.BibDocument.read(output)
+    assert written.entries["inline"].fields["title"].value == "Inline Raw"
 
 
 def test_raw_bib_document_accepts_permissive_citation_keys() -> None:
@@ -1680,7 +1686,7 @@ def test_raw_bib_document_duplicate_fields_are_addressable_by_occurrence(tmp_pat
 
     entry = raw.entries["duplicate"]
     assert entry.fields.unique_keys() == ["title", "year"]
-    assert [field.name for field in entry.fields.occurrences()] == ["title", "title", "year"]
+    assert [field.name for field in entry.fields.occurrences()] == ["title", "TITLE", "year"]
     titles = entry.fields.get_all("title")
     assert [field.value for field in titles] == ["First", "Second"]
 
@@ -1847,3 +1853,110 @@ def test_raw_bib_document_allows_no_space_comment_after_bare_value(tmp_path: Pat
 
     assert raw.failed_blocks == []
     assert raw.entries["commented"].fields["year"].value == "2024"
+
+
+def test_tidy_bibtex_formats_text_and_reports_count() -> None:
+    result = rk.tidy_bibtex(
+        """@ARTICLE {feinberg1983technique,
+    number={1},
+  pages={6-13},
+  year={1983},}
+"""
+    )
+
+    assert result.count == 1
+    assert result.warnings == []
+    assert result.bibtex == (
+        "@article{feinberg1983technique,\n"
+        "  number        = {1},\n"
+        "  pages         = {6--13},\n"
+        "  year          = {1983}\n"
+        "}\n"
+    )
+
+
+def test_tidy_options_enable_default_field_sorting() -> None:
+    result = rk.tidy_bibtex(
+        """@article{doe2024,
+  year={2024},
+  title={Fast Citations},
+  author={Doe, Jane}
+}
+""",
+        options=rk.TidyOptions(sort_fields=True),
+    )
+
+    assert result.bibtex.index("title") < result.bibtex.index("author")
+    assert result.bibtex.index("author") < result.bibtex.index("year")
+
+
+def test_tidy_bibtex_returns_structured_warnings() -> None:
+    result = rk.tidy_bibtex(
+        """@article{
+  title={Missing key}
+}
+"""
+    )
+
+    assert result.count == 1
+    assert [(warning.code, warning.rule) for warning in result.warnings] == [("missing_key", None)]
+    assert "citation key" in result.warnings[0].message
+
+
+def test_tidy_bibtex_raises_structured_syntax_error() -> None:
+    with pytest.raises(rk.TidySyntaxError) as raised:
+        rk.tidy_bibtex("@article{broken,\n  title = {No close}\n")
+
+    err = raised.value
+    assert err.line == 1
+    assert err.column == 1
+    assert err.byte == 0
+    assert err.character == "@"
+    assert err.message
+
+
+def test_bib_document_tidy_uses_current_raw_state() -> None:
+    raw = rk.BibDocument.parse(
+        """@article{doe2024,
+  title={Old title},
+  year={2024}
+}
+"""
+    )
+    raw.entries["doe2024"].fields["title"].value = "Corrected title"
+
+    result = raw.tidy(options=rk.TidyOptions(sort_fields=True))
+
+    assert "Corrected title" in result.bibtex
+    assert raw.to_bibtex().count("Corrected title") == 1
+
+
+def test_tidy_file_writes_output_when_requested(tmp_path: Path) -> None:
+    source = tmp_path / "refs.bib"
+    output = tmp_path / "refs.tidy.bib"
+    source.write_text(
+        """@ARTICLE {doe2024,
+  pages={6-13},
+  year={2024},}
+""",
+        encoding="utf-8",
+    )
+
+    result = rk.tidy_file(source, output=output)
+
+    assert output.read_text(encoding="utf-8") == result.bibtex
+    assert "@article{doe2024" in result.bibtex
+
+
+def test_tidy_file_can_return_result_without_writing(tmp_path: Path) -> None:
+    source = tmp_path / "refs.bib"
+    original = """@ARTICLE {doe2024,
+  pages={6-13},
+  year={2024},}
+"""
+    source.write_text(original, encoding="utf-8")
+
+    result = rk.tidy_file(source)
+
+    assert source.read_text(encoding="utf-8") == original
+    assert "@article{doe2024" in result.bibtex

{refkit-0.0.2 → refkit-0.0.3}/tests/test_pyodide.py

@@ -31,6 +31,11 @@ CORE_EXPORTS = (
     "Rendered",
     "RenderedDocument",
     "Style",
+    "TidyError",
+    "TidyOptions",
+    "TidyResult",
+    "TidySyntaxError",
+    "TidyWarning",
 )
 
 
@@ -42,18 +47,21 @@ def _fake_core_module(name: str, *, version: str) -> ModuleType:
     dynamic_module.build_mode = "release"
     for export in CORE_EXPORTS:
         setattr(module, export, type(export, (), {}))
+    dynamic_module.tidy_bibtex = lambda source, *, options=None: source
+    dynamic_module._tidy_option_names = []
     return module
 
 
 def test_mock_pyodide_sets_platform_and_stub_modules(mock_pyodide: Any) -> None:
     micropip = ModuleType("micropip")
+    previous_micropip = sys.modules.get("micropip")
 
     with mock_pyodide(micropip=micropip):
         assert sys.platform == "emscripten"
         assert importlib.import_module("pyodide") is sys.modules["pyodide"]
         assert importlib.import_module("micropip") is micropip
 
-    assert sys.modules.get("micropip") is not micropip
+    assert sys.modules.get("micropip") is previous_micropip
 
 
 def test_pyodide_env_fixture_sets_platform(pyodide_env: None) -> None:

refkit-0.0.3/tests/test_tidy_options.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import ast
+import inspect
+from pathlib import Path
+from typing import Any, cast
+
+import pytest
+
+import refkit as rk
+import refkit_core
+
+WORKSPACE = Path(__file__).parents[2]
+CORE_STUB = WORKSPACE / "refkit-core" / "src" / "refkit_core" / "_refkit_core.pyi"
+EXPECTED_TIDY_OPTION_NAMES = (
+    "omit",
+    "curly",
+    "numeric",
+    "months",
+    "space",
+    "tab",
+    "align",
+    "blank_lines",
+    "sort",
+    "duplicates",
+    "merge",
+    "strip_enclosing_braces",
+    "drop_all_caps",
+    "escape",
+    "sort_fields",
+    "strip_comments",
+    "trailing_commas",
+    "encode_urls",
+    "tidy_comments",
+    "remove_empty_fields",
+    "remove_duplicate_fields",
+    "generate_keys",
+    "max_authors",
+    "lowercase",
+    "enclosing_braces",
+    "remove_braces",
+    "wrap",
+)
+
+
+def _stub_tidy_option_names() -> tuple[str, ...]:
+    module = ast.parse(CORE_STUB.read_text(encoding="utf-8"))
+    for node in module.body:
+        if isinstance(node, ast.ClassDef) and node.name == "TidyOptions":
+            init = next(
+                item
+                for item in node.body
+                if isinstance(item, ast.FunctionDef) and item.name == "__init__"
+            )
+            return tuple(arg.arg for arg in init.args.kwonlyargs)
+    raise AssertionError("TidyOptions stub not found")
+
+
+def test_tidy_options_stub_lists_public_keywords() -> None:
+    assert _stub_tidy_option_names() == EXPECTED_TIDY_OPTION_NAMES
+
+
+def test_tidy_options_native_allowlist_lists_public_keywords() -> None:
+    assert tuple(refkit_core._tidy_option_names) == EXPECTED_TIDY_OPTION_NAMES
+
+
+def test_tidy_options_runtime_signature_lists_public_keywords() -> None:
+    signature = inspect.signature(rk.TidyOptions)
+
+    assert tuple(signature.parameters) == EXPECTED_TIDY_OPTION_NAMES
+    assert signature.parameters["space"].default == 2
+    assert signature.parameters["escape"].default is True
+    assert signature.parameters["sort_fields"].default is None
+
+
+def test_tidy_options_reject_unknown_names() -> None:
+    options_type = cast(Any, rk.TidyOptions)
+    with pytest.raises(ValueError, match="unknown tidy option"):
+        options_type(unknown=True)
+
+
+@pytest.mark.parametrize(
+    ("option", "value", "message"),
+    [
+        ("sort_fields", "title", "iterable of strings"),
+        ("duplicates", ["bogus"], "unknown duplicate rule"),
+        ("merge", "bogus", "unknown merge strategy"),
+        ("wrap", "wide", "integer"),
+        ("space", "two", "integer"),
+        ("space", True, "integer"),
+        ("max_authors", False, "integer"),
+    ],
+)
+def test_tidy_options_validate_representative_values(
+    option: str,
+    value: object,
+    message: str,
+) -> None:
+    options_type = cast(Any, rk.TidyOptions)
+    with pytest.raises((TypeError, ValueError), match=message):
+        options_type(**{option: value})
+
+
+def test_tidy_options_default_toggles_forward_to_formatter() -> None:
+    source = """@article{doe2024,
+  year={2024},
+  title={Fast Citations},
+  author={Doe, Jane}
+}
+"""
+
+    sorted_fields = rk.tidy_bibtex(source, options=rk.TidyOptions(sort_fields=True))
+    assert sorted_fields.bibtex.index("title") < sorted_fields.bibtex.index("author")
+
+    wrapped = rk.tidy_bibtex(
+        (
+            "@article{wide, title={One two three four five six seven eight nine "
+            "ten eleven twelve thirteen fourteen fifteen sixteen}}\n"
+        ),
+        options=rk.TidyOptions(wrap=True),
+    )
+    assert "\n    One two" in wrapped.bibtex
+
+    generated = rk.tidy_bibtex(
+        "@article{old, author={Doe, Jane}, title={Fast Citations}, year={2024}}\n",
+        options=rk.TidyOptions(generate_keys=True),
+    )
+    assert "@article{doe2024fast," in generated.bibtex
+
+    duplicate = rk.tidy_bibtex(
+        """
+@article{first, title={Same}, doi={10.1/example}, year={2024}}
+@article{second, title={Same}, doi={10.1/example}, year={2025}}
+""",
+        options=rk.TidyOptions(duplicates=["doi"], merge="first"),
+    )
+    assert [warning.rule for warning in duplicate.warnings] == ["doi"]
+    assert duplicate.count == 2
+    assert duplicate.bibtex.count("@article") == 1
+    assert duplicate.bibtex == (
+        "@article{first,\n"
+        "  title         = {Same},\n"
+        "  doi           = {10.1/example},\n"
+        "  year          = {2024}\n"
+        "}\n"
+    )
+
+
+def test_tidy_options_constructor_rejects_positional_arguments() -> None:
+    options_type = cast(Any, rk.TidyOptions)
+    with pytest.raises(TypeError):
+        options_type(True)

{refkit-0.0.2 → refkit-0.0.3}/tests/test_type_contracts.py

@@ -19,6 +19,10 @@ def failed_block_errors(raw: rk.BibDocument) -> list[str]:
     return [block["error"] for block in raw.failed_blocks]
 
 
+def tidy_warning_codes(result: rk.TidyResult) -> list[str]:
+    return [warning.code for warning in result.warnings]
+
+
 def duplicate_entry_titles(raw: rk.BibDocument, key: str) -> list[str]:
     return [
         field.value for entry in raw.entries.get_all(key) for field in entry.fields.get_all("title")
@@ -32,12 +36,17 @@ def test_type_checked_structured_return_samples() -> None:
 
     rendered = doc.render([rk.Citation("first", "doe2024")])
 
-    assert rendered_tree_kinds(rendered["first"])
-    assert all(start >= 0 for start in raw_block_starts(raw))
-    assert all(error for error in failed_block_errors(raw))
+    assert rendered_tree_kinds(rendered["first"]) == ["Text", "Element", "Text"]
+    assert raw_block_starts(raw)[0] == 0
+    assert failed_block_errors(raw) == ["entry ended before closing delimiter"]
     duplicate_raw = rk.BibDocument.read(FIXTURES / "raw-duplicates.bib")
     assert duplicate_entry_titles(duplicate_raw, "dup") == [
         "First Title",
         "Second Title",
         "Duplicate Entry",
     ]
+    tidied = rk.BibDocument.parse("@article{typed, title={Typed Contract}, year={2024}}\n").tidy(
+        options=rk.TidyOptions(strip_comments=True)
+    )
+    assert isinstance(tidied.bibtex, str)
+    assert tidy_warning_codes(tidied) == []