release: prepare v0.1.0 validation

.github/workflows/project-sync-safety.yml

@@ -41,10 +41,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -54,7 +54,7 @@ jobs:
 
       - name: Check focused formatting
         run: >-
-          python -m black --check --diff
+          python -m ruff format --check
           src/docmergeforge/project/sync.py
           src/docmergeforge/project/drift.py
           src/docmergeforge/project/discovery.py

.github/workflows/quality.yml

@@ -31,8 +31,9 @@ jobs:
       - run: python -m pip install --upgrade pip
       - run: pip install -e ".[dev,web]"
       - run: pre-commit validate-config
+      # Keep CI formatting aligned with the pinned Ruff pre-commit policy.
       - run: ruff check .
-      - run: black --check --diff .
+      - run: ruff format --check .
       - run: mypy src/docmergeforge
       - run: python scripts/check_docs_links.py
       - run: python scripts/check_repository_reference.py

.github/workflows/regression.yml

@@ -28,7 +28,7 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libegl1
       - run: python -m pip install --upgrade pip
-      - run: pip install -e ".[dev]"
+      - run: pip install -e ".[dev,web]"
       - run: python scripts/generate_120_fixture.py fixtures/generated/sql-120
       - run: pytest -m "regression or integration" tests/regression tests/integration
       - run: docmergeforge validate --input fixtures/generated/sql-120 --parts 1-120

docs/build/release-checklist.md

@@ -26,7 +26,7 @@ At the intended release commit:
 - [ ] Quality workflow green.
 - [ ] `pre-commit validate-config` green.
 - [ ] Ruff green.
-- [ ] Black green.
+- [ ] Ruff formatting green.
 - [ ] strict mypy green.
 - [ ] repository-local Markdown link integrity green.
 - [ ] full pytest green.

docs/history/what_changed-through-2026-08-20-cross-platform.md

@@ -1,6 +1,6 @@
 # What Changed
 
-This file records the current DocMergeForge development pass, verification evidence, and remaining release gates. Earlier detailed development history is preserved in [`docs/history/what_changed-through-2026-08-18.md`](docs/history/what_changed-through-2026-08-18.md) so this top-level record stays readable instead of growing without bound.
+This file records the current DocMergeForge development pass, verification evidence, and remaining release gates. Earlier detailed development history is preserved in [`what_changed-through-2026-08-18.md`](what_changed-through-2026-08-18.md) so this top-level record stays readable instead of growing without bound.
 
 An item is not treated as finished merely because code was pushed. CI, packaging, platform acceptance, external-office fidelity evidence, accessibility review, and release-signing evidence remain separate completion gates.
 

pyproject.toml

@@ -46,8 +46,7 @@ Funding = "https://buymeacoffee.com/sanskarIN"
 dev = [
   "pytest>=8.3",
   "pytest-cov>=6",
-  "ruff>=0.9",
-  "black>=25.1",
+  "ruff==0.16.3",
   "mypy>=1.15",
   "pre-commit>=4",
   "types-setuptools",
@@ -73,6 +72,7 @@ packages = ["src/docmergeforge"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["."]
 addopts = "-q --strict-markers"
 markers = [
   "integration: tests requiring document libraries",
@@ -86,9 +86,9 @@ target-version = "py312"
 [tool.ruff.lint]
 select = ["E", "F", "I", "B", "UP", "SIM", "C4"]
 
-[tool.black]
-line-length = 100
-target-version = ["py312"]
+[tool.ruff.lint.per-file-ignores]
+"src/docmergeforge/ui/main.py" = ["SIM103"]
+"src/docmergeforge/web/app.py" = ["E501"]
 
 [tool.mypy]
 python_version = "3.12"

scripts/check_docx_fidelity_acceptance.py

@@ -13,9 +13,7 @@ def build_fixture(path: Path) -> None:
     document = Document()
     document.core_properties.title = "DocMergeForge Fidelity Acceptance"
     document.add_heading("Fidelity Acceptance", level=1)
-    document.add_paragraph(
-        "Representative smoke content with bold, italic, and list formatting."
-    )
+    document.add_paragraph("Representative smoke content with bold, italic, and list formatting.")
     formatted = document.add_paragraph()
     formatted.add_run("Bold text").bold = True
     formatted.add_run(" and ")

scripts/generate_120_fixture.py

@@ -47,8 +47,7 @@ def main() -> int:
             zf.writestr("example.sql", f"-- Part {part}\nSELECT {part};\n")
 
     print(
-        "Generated 120 PDF, 120 DOCX, and 120 independent companion ZIP fixtures "
-        f"in {args.output}"
+        f"Generated 120 PDF, 120 DOCX, and 120 independent companion ZIP fixtures in {args.output}"
     )
     return 0
 

src/docmergeforge/cli/main.py

@@ -278,9 +278,7 @@ def _run_direct_merge(args: argparse.Namespace) -> int:
                         "ready": False,
                         "missing": validation_result.missing_parts,
                         "duplicates": validation_result.duplicate_parts,
-                        "diagnostics": [
-                            item.to_dict() for item in validation_result.diagnostics
-                        ],
+                        "diagnostics": [item.to_dict() for item in validation_result.diagnostics],
                     },
                     indent=2,
                 )

src/docmergeforge/diagnostics/logging.py

@@ -15,9 +15,7 @@
     r"(?P=quote)?"
 )
 _BEARER_PATTERN = re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+")
-_AUTH_HEADER_PATTERN = re.compile(
-    r"(?i)\bAuthorization\s*:\s*(?:Basic|Bearer)\s+[^\s,;]+"
-)
+_AUTH_HEADER_PATTERN = re.compile(r"(?i)\bAuthorization\s*:\s*(?:Basic|Bearer)\s+[^\s,;]+")
 _API_KEY_HEADER_PATTERN = re.compile(r"(?i)\b(?:X-)?Api-Key\s*:\s*[^\s,;]+")
 
 
@@ -57,13 +55,14 @@ def configure_logging(path: Path, level: str = "INFO") -> logging.Logger:
     logger.setLevel(getattr(logging, level.upper(), logging.INFO))
     logger.propagate = False
 
-    for handler in list(logger.handlers):
-        handler.close()
-        logger.removeHandler(handler)
+    for existing_handler in list(logger.handlers):
+        existing_handler.close()
+        logger.removeHandler(existing_handler)
 
+    handler: logging.Handler
     try:
         path.parent.mkdir(parents=True, exist_ok=True)
-        handler: logging.Handler = RotatingFileHandler(
+        handler = RotatingFileHandler(
             path,
             maxBytes=5 * 1024 * 1024,
             backupCount=3,

src/docmergeforge/discovery/scanner.py

@@ -58,9 +58,7 @@ def _iter_directory(
     for directory, directory_names, file_names in os.walk(root, followlinks=False):
         directory_path = Path(directory)
         directory_names[:] = [
-            name
-            for name in directory_names
-            if not _is_excluded(directory_path / name, excluded)
+            name for name in directory_names if not _is_excluded(directory_path / name, excluded)
         ]
         for name in file_names:
             path = directory_path / name

src/docmergeforge/docx/engine.py

@@ -132,7 +132,7 @@ def merge(
             diagnostics = validate_docx_package(temporary)
             if any(diag.level.value in {"ERROR", "FATAL"} for diag in diagnostics):
                 raise ValidationError(
-                    "Output DOCX package validation failed: " f"{diagnostics[0].message}"
+                    f"Output DOCX package validation failed: {diagnostics[0].message}"
                 )
 
             Document(str(temporary))

src/docmergeforge/docx/fidelity_acceptance.py

@@ -128,12 +128,8 @@ def snapshot_docx_structure(path: Path) -> DocxStructureSnapshot:
         inline_shapes=len(document.inline_shapes),
         sections=len(document.sections),
         headings=headings,
-        header_paragraphs=sum(
-            len(section.header.paragraphs) for section in document.sections
-        ),
-        footer_paragraphs=sum(
-            len(section.footer.paragraphs) for section in document.sections
-        ),
+        header_paragraphs=sum(len(section.header.paragraphs) for section in document.sections),
+        footer_paragraphs=sum(len(section.footer.paragraphs) for section in document.sections),
         header_tables=sum(len(section.header.tables) for section in document.sections),
         footer_tables=sum(len(section.footer.tables) for section in document.sections),
     )
@@ -152,9 +148,7 @@ def snapshot_docx_content(path: Path) -> DocxContentSnapshot:
         footer_texts.extend(_table_texts(section.footer.tables))
 
     return DocxContentSnapshot(
-        body_paragraphs_sha256=_digest_texts(
-            paragraph.text for paragraph in document.paragraphs
-        ),
+        body_paragraphs_sha256=_digest_texts(paragraph.text for paragraph in document.paragraphs),
         tables_sha256=_digest_texts(_table_texts(document.tables)),
         headers_sha256=_digest_texts(header_texts),
         footers_sha256=_digest_texts(footer_texts),

src/docmergeforge/docx/fidelity_corpus.py

@@ -67,11 +67,7 @@ def stopped_early(self) -> bool:
 
     @property
     def accepted(self) -> bool:
-        return (
-            self.discovered_count > 0
-            and not self.stopped_early
-            and self.failed_count == 0
-        )
+        return self.discovered_count > 0 and not self.stopped_early and self.failed_count == 0
 
     def to_dict(self) -> dict[str, Any]:
         return {

src/docmergeforge/docx/libreoffice_uno_acceptance.py

@@ -227,9 +227,7 @@ def run_libreoffice_uno_acceptance(
     capability = require_fidelity_automation("libreoffice")
     uno_python = find_uno_python()
     if uno_python is None:
-        raise ValidationError(
-            "LibreOffice UNO acceptance requires a Python UNO bridge."
-        )
+        raise ValidationError("LibreOffice UNO acceptance requires a Python UNO bridge.")
     libreoffice_uno_merge_documents(
         ordered,
         output,

src/docmergeforge/docx/libreoffice_uno_merge.py

@@ -20,7 +20,7 @@
 )
 from docmergeforge.utilities.hashing import sha256_file
 
-_UNO_WORKER = r'''
+_UNO_WORKER = r"""
 from __future__ import annotations
 
 import argparse
@@ -142,7 +142,7 @@ def main() -> int:
 
 if __name__ == "__main__":
     raise SystemExit(main())
-'''.strip()
+""".strip()
 
 
 @dataclass(slots=True, frozen=True)
@@ -371,9 +371,7 @@ def libreoffice_uno_merge_documents(
                 text=True,
             )
             try:
-                worker_stdout, worker_stderr = worker_process.communicate(
-                    timeout=timeout_seconds
-                )
+                worker_stdout, worker_stderr = worker_process.communicate(timeout=timeout_seconds)
             except subprocess.TimeoutExpired as exc:
                 worker_process.kill()
                 worker_stdout, worker_stderr = worker_process.communicate()
@@ -383,8 +381,7 @@ def libreoffice_uno_merge_documents(
             if worker_process.returncode != 0:
                 detail = worker_stderr.strip() or worker_stdout.strip()
                 raise ValidationError(
-                    "LibreOffice UNO merge worker failed"
-                    + (f": {detail}" if detail else ".")
+                    "LibreOffice UNO merge worker failed" + (f": {detail}" if detail else ".")
                 )
         finally:
             if worker_process is not None and worker_process.poll() is None:

src/docmergeforge/docx/section_evidence.py

@@ -68,9 +68,7 @@ def page_number_section_records(path: Path) -> tuple[PageNumberSectionRecord, ..
             try:
                 document_xml = archive.read(_DOCUMENT_XML)
             except KeyError as exc:
-                raise ValidationError(
-                    f"DOCX package is missing {_DOCUMENT_XML}: {path}"
-                ) from exc
+                raise ValidationError(f"DOCX package is missing {_DOCUMENT_XML}: {path}") from exc
     except zipfile.BadZipFile as exc:
         raise ValidationError(f"Invalid DOCX ZIP container: {path}") from exc
 
@@ -118,8 +116,6 @@ def page_number_properties_sha256(paths: Sequence[Path]) -> str:
     global_section_index = 0
     for path in paths:
         for record in page_number_section_records(path):
-            canonical_records.append(
-                f"section={global_section_index}|{record.canonical()}"
-            )
+            canonical_records.append(f"section={global_section_index}|{record.canonical()}")
             global_section_index += 1
     return _digest_records(canonical_records)

src/docmergeforge/docx/word.py

@@ -70,10 +70,10 @@ def word_roundtrip_copy(
         raise ValidationError("Microsoft Word fidelity round-trip accepts DOCX paths only.")
     if not source.exists() or not source.is_file():
         raise FileNotFoundError(source)
-    if destination.exists():
-        raise FileExistsError(f"Refusing to overwrite existing DOCX output: {destination}")
     if source.resolve() == destination.resolve():
         raise ValidationError("Microsoft Word fidelity round-trip requires a separate output path.")
+    if destination.exists():
+        raise FileExistsError(f"Refusing to overwrite existing DOCX output: {destination}")
 
     host = powershell or find_word_powershell_host()
     if host is None:

src/docmergeforge/docx/word_merge_acceptance.py

@@ -130,19 +130,15 @@ def _table_texts(tables: Iterable[Any]) -> list[str]:
 def _header_texts(document: Any) -> list[str]:
     values: list[str] = []
     for section in document.sections:
-        values.extend(
-            paragraph.text for paragraph in section.header.paragraphs if paragraph.text
-        )
+        values.extend(paragraph.text for paragraph in section.header.paragraphs if paragraph.text)
         values.extend(_table_texts(section.header.tables))
     return values
 
 
 def _footer_texts(document: Any) -> list[str]:
     values: list[str] = []
     for section in document.sections:
-        values.extend(
-            paragraph.text for paragraph in section.footer.paragraphs if paragraph.text
-        )
+        values.extend(paragraph.text for paragraph in section.footer.paragraphs if paragraph.text)
         values.extend(_table_texts(section.footer.tables))
     return values
 
@@ -181,18 +177,13 @@ def _section_record(section: Any) -> str:
             f"gutter={_scalar(section.gutter)}",
             f"header_distance={_scalar(section.header_distance)}",
             f"footer_distance={_scalar(section.footer_distance)}",
-            "different_first_page="
-            f"{int(bool(section.different_first_page_header_footer))}",
+            f"different_first_page={int(bool(section.different_first_page_header_footer))}",
             f"header_linked={int(bool(section.header.is_linked_to_previous))}",
-            "first_header_linked="
-            f"{int(bool(section.first_page_header.is_linked_to_previous))}",
-            "even_header_linked="
-            f"{int(bool(section.even_page_header.is_linked_to_previous))}",
+            f"first_header_linked={int(bool(section.first_page_header.is_linked_to_previous))}",
+            f"even_header_linked={int(bool(section.even_page_header.is_linked_to_previous))}",
             f"footer_linked={int(bool(section.footer.is_linked_to_previous))}",
-            "first_footer_linked="
-            f"{int(bool(section.first_page_footer.is_linked_to_previous))}",
-            "even_footer_linked="
-            f"{int(bool(section.even_page_footer.is_linked_to_previous))}",
+            f"first_footer_linked={int(bool(section.first_page_footer.is_linked_to_previous))}",
+            f"even_footer_linked={int(bool(section.even_page_footer.is_linked_to_previous))}",
         )
     )
 
@@ -205,9 +196,7 @@ def _section_properties_sha256(paths: Sequence[Path]) -> str:
     for path in paths:
         document = Document(str(path))
         for section in document.sections:
-            records.append(
-                f"section={global_section_index}|{_section_record(section)}"
-            )
+            records.append(f"section={global_section_index}|{_section_record(section)}")
             global_section_index += 1
     return _digest_texts(records)
 
@@ -315,9 +304,7 @@ def _validate_acceptance_inputs(
     return ordered_sources
 
 
-def _verify_source_hashes(
-    sources: Sequence[Path], source_hashes: Sequence[str]
-) -> None:
+def _verify_source_hashes(sources: Sequence[Path], source_hashes: Sequence[str]) -> None:
     for source, expected_hash in zip(sources, source_hashes, strict=True):
         verify_native_source_unchanged(source, expected_hash)