markdown-gost 0.2.0__tar.gz

markdown_gost-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arseniy Mikheev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markdown_gost-0.2.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: markdown-gost
+Version: 0.2.0
+Summary: Markdown to GOST 7.32 DOCX/PDF converter with an HTML preview engine
+License-Expression: MIT
+License-File: LICENSE
+Author: Arseniy Mikheev
+Requires-Python: >=3.13,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: pdf
+Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: freetype-py (>=2.5.0,<3.0.0)
+Requires-Dist: latex2mathml (>=3.76.0,<4.0.0)
+Requires-Dist: lxml (>=5.0.0,<6.0.0)
+Requires-Dist: marko (>=2.1.0,<3.0.0)
+Requires-Dist: pillow (>=11.0.0,<12.0.0)
+Requires-Dist: pydantic (>=2.10.0,<3.0.0)
+Requires-Dist: pygments (>=2.18.0,<3.0.0)
+Requires-Dist: python-docx (>=1.2.0,<2.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: unoserver (>=3.0,<4.0) ; extra == "pdf"
+Description-Content-Type: text/markdown
+
+# markdown-gost
+
+Markdown to GOST 7.32 DOCX/PDF converter with a paginated HTML preview.
+
+- [Syntax reference](skills/markdown-gost/syntax.md) — extended Markdown: tables, listings, equations, appendices, bibliography, templates
+- [Architecture](docs/architecture.md) — pipeline, config system, storage protocol, testing tiers
+
+## Install
+
+```bash
+pipx install markdown-gost            # DOCX + preview
+pipx install "markdown-gost[pdf]"     # + unoserver tooling
+```
+
+PDF output requires a running [unoserver](https://github.com/unoconv/unoserver)
+(`pipx install unoserver && unoserver &`), reachable via `UNOSERVER_HOST` /
+`UNOSERVER_PORT` (default `127.0.0.1:2003`).
+Import requires pandoc >= 2.19 in PATH (`PANDOC_BINARY` to override).
+Fonts for accurate pagination: `apt install fontconfig fonts-liberation
+fonts-dejavu` (macOS: `brew install fontconfig font-liberation`).
+
+Docker image with LibreOffice, unoserver, pandoc and fonts included:
+
+```bash
+docker run --rm -v "$PWD":/work -w /work ghcr.io/grenition/markdown-gost:0.2.0 \
+  convert paper.md -o paper.docx
+```
+
+## Agent skill
+
+```bash
+npx skills add grenition/markdown-gost          # skills.sh registry: Claude Code, Cursor, Codex, opencode, ...
+cp -r skills/markdown-gost ~/.claude/skills/    # or copy into your harness skills directory
+```
+
+## Commands
+
+```bash
+markdown-gost convert input.md -o out.docx
+markdown-gost convert input.md -o out.pdf                 # needs unoserver
+markdown-gost convert input.md -o out.docx --config my.yaml
+markdown-gost validate input.md
+markdown-gost import legacy.docx -o imported.md           # needs pandoc
+markdown-gost import legacy.pdf -o imported.md            # needs pandoc + unoserver
+```
+
+Config: YAML with presets (`default`, `gost-7-32-2017`, `mirea-practice`),
+selected inside the file (`preset: gost-7-32-2017`), any field overridable.
+Full schema: `markdown_gost.config.schema.Config.model_json_schema()`.
+
+Preview API:
+
+```python
+from markdown_gost.preview import build_preview_model, render_preview_html
+
+document = build_preview_model(markdown_text, config)
+html = render_preview_html(document)
+```
+
+Object stores are not bundled: implement the `Storage` protocol and pass your
+implementation to the conversion APIs.
+
+## Development
+
+Python 3.13, Poetry 2.x.
+
+```bash
+poetry install
+make test-unit
+make test-integration
+make test-screenshot      # pixel-diff merge gate
+make lint typecheck
+make test-in-docker       # full suite in the test image
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+

markdown_gost-0.2.0/README.md

@@ -0,0 +1,78 @@
+# markdown-gost
+
+Markdown to GOST 7.32 DOCX/PDF converter with a paginated HTML preview.
+
+- [Syntax reference](skills/markdown-gost/syntax.md) — extended Markdown: tables, listings, equations, appendices, bibliography, templates
+- [Architecture](docs/architecture.md) — pipeline, config system, storage protocol, testing tiers
+
+## Install
+
+```bash
+pipx install markdown-gost            # DOCX + preview
+pipx install "markdown-gost[pdf]"     # + unoserver tooling
+```
+
+PDF output requires a running [unoserver](https://github.com/unoconv/unoserver)
+(`pipx install unoserver && unoserver &`), reachable via `UNOSERVER_HOST` /
+`UNOSERVER_PORT` (default `127.0.0.1:2003`).
+Import requires pandoc >= 2.19 in PATH (`PANDOC_BINARY` to override).
+Fonts for accurate pagination: `apt install fontconfig fonts-liberation
+fonts-dejavu` (macOS: `brew install fontconfig font-liberation`).
+
+Docker image with LibreOffice, unoserver, pandoc and fonts included:
+
+```bash
+docker run --rm -v "$PWD":/work -w /work ghcr.io/grenition/markdown-gost:0.2.0 \
+  convert paper.md -o paper.docx
+```
+
+## Agent skill
+
+```bash
+npx skills add grenition/markdown-gost          # skills.sh registry: Claude Code, Cursor, Codex, opencode, ...
+cp -r skills/markdown-gost ~/.claude/skills/    # or copy into your harness skills directory
+```
+
+## Commands
+
+```bash
+markdown-gost convert input.md -o out.docx
+markdown-gost convert input.md -o out.pdf                 # needs unoserver
+markdown-gost convert input.md -o out.docx --config my.yaml
+markdown-gost validate input.md
+markdown-gost import legacy.docx -o imported.md           # needs pandoc
+markdown-gost import legacy.pdf -o imported.md            # needs pandoc + unoserver
+```
+
+Config: YAML with presets (`default`, `gost-7-32-2017`, `mirea-practice`),
+selected inside the file (`preset: gost-7-32-2017`), any field overridable.
+Full schema: `markdown_gost.config.schema.Config.model_json_schema()`.
+
+Preview API:
+
+```python
+from markdown_gost.preview import build_preview_model, render_preview_html
+
+document = build_preview_model(markdown_text, config)
+html = render_preview_html(document)
+```
+
+Object stores are not bundled: implement the `Storage` protocol and pass your
+implementation to the conversion APIs.
+
+## Development
+
+Python 3.13, Poetry 2.x.
+
+```bash
+poetry install
+make test-unit
+make test-integration
+make test-screenshot      # pixel-diff merge gate
+make lint typecheck
+make test-in-docker       # full suite in the test image
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

markdown_gost-0.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "markdown-gost"
+version = "0.2.0"
+description = "Markdown to GOST 7.32 DOCX/PDF converter with an HTML preview engine"
+authors = [{ name = "Arseniy Mikheev" }]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.13,<4.0"
+dependencies = [
+    "marko (>=2.1.0,<3.0.0)",
+    "python-docx (>=1.2.0,<2.0.0)",
+    "pyyaml (>=6.0.2,<7.0.0)",
+    "pydantic (>=2.10.0,<3.0.0)",
+    "click (>=8.1.0,<9.0.0)",
+    "pygments (>=2.18.0,<3.0.0)",
+    "pillow (>=11.0.0,<12.0.0)",
+    "freetype-py (>=2.5.0,<3.0.0)",
+    "latex2mathml (>=3.76.0,<4.0.0)",
+    "lxml (>=5.0.0,<6.0.0)",
+]
+
+[project.optional-dependencies]
+pdf = ["unoserver (>=3.0,<4.0)"]
+
+[project.scripts]
+markdown-gost = "markdown_gost.cli.__main__:cli"
+
+[tool.poetry]
+packages = [{ include = "markdown_gost", from = "src" }]
+include = [{ path = "src/markdown_gost/render/_assets/*.xsl", format = ["sdist", "wheel"] }]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.0"
+pytest-cov = "^6.0.0"
+ruff = "^0.9.0"
+mypy = "^1.13.0"
+pdf2image = "^1.17.0"
+unoserver = "^3.0.0"
+types-pyyaml = "^6.0.12"
+playwright = "^1.61.0"
+# The metrics stack stays optional for end users, but the test suite
+# asserts its real behaviour.
+prometheus-client = ">=0.21.0,<1.0.0"
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/markdown_gost/__init__.py:__version__"]
+tag_format = "v{version}"
+commit_message = "chore(release): v{version} [skip ci]"
+major_on_zero = true
+build_command = "python -m pip install --quiet build && python -m build --outdir dist"
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]

markdown_gost-0.2.0/src/markdown_gost/__init__.py

@@ -0,0 +1,5 @@
+from markdown_gost.convert import convert
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__", "convert"]

markdown_gost-0.2.0/src/markdown_gost/cli/__main__.py

@@ -0,0 +1,191 @@
+"""markdown-gost CLI (T020).
+
+Commands: ``convert``, ``validate``. Exit codes: ``0`` ok, ``1`` user error
+(config/parse), ``2`` system error / usage error.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, NoReturn, cast
+
+import click
+import yaml
+
+from markdown_gost import __version__
+from markdown_gost.cli.commands.import_cmd import import_command
+from markdown_gost.config.errors import ConfigError
+from markdown_gost.config.loader import load_config_from_path, load_config_from_string
+from markdown_gost.config.schema import Config
+from markdown_gost.convert import Format
+from markdown_gost.convert import convert as convert_pipeline
+from markdown_gost.core.parser import parse as parse_markdown
+from markdown_gost.storage import get_storage
+
+_DEFAULT_CONFIG = "preset: default\n"
+_VALID_FORMATS: tuple[str, ...] = ("docx", "pdf")
+_LOGGER = logging.getLogger("markdown_gost.cli")
+
+
+def _resolve_format(explicit: str | None, output: Path | None) -> Format:
+    if explicit is not None:
+        return cast(Format, explicit.lower())
+    if output is not None:
+        suffix = output.suffix.lstrip(".").lower()
+        if suffix in _VALID_FORMATS:
+            return cast(Format, suffix)
+    return "docx"
+
+
+def _load_config(config_path: Path | None) -> Config:
+    if config_path is None:
+        return load_config_from_string(_DEFAULT_CONFIG)
+    return load_config_from_path(config_path)
+
+
+def _user_error(message: str) -> NoReturn:
+    raise click.ClickException(message)
+
+
+def _system_error(message: str) -> NoReturn:
+    click.echo(f"Error: {message}", err=True)
+    sys.exit(2)
+
+
+def _execute(action: Callable[[], Any]) -> Any:
+    """Run *action* and translate exceptions to documented exit codes.
+
+    ``ConfigError`` / ``ValueError`` (incl. pydantic ``ValidationError``) /
+    ``yaml.YAMLError`` → exit 1. Anything else → exit 2.
+    """
+
+    try:
+        return action()
+    except click.ClickException:
+        raise
+    except (ConfigError, ValueError, yaml.YAMLError) as exc:
+        _user_error(str(exc))
+    except Exception as exc:
+        _LOGGER.debug("system error", exc_info=True)
+        _system_error(str(exc))
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="markdown-gost")
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Enable DEBUG-level logging.",
+)
+def cli(verbose: bool) -> None:
+    """markdown-gost — Markdown → DOCX/PDF по ГОСТ.
+
+    Пресет ГОСТа задаётся в YAML-конфиге, не флагом CLI (см. ADR-0004).
+    """
+
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(levelname)s %(name)s: %(message)s",
+        force=True,
+    )
+
+
+@cli.command("convert")
+@click.argument(
+    "input_path",
+    metavar="INPUT",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Output file. Defaults to <input>.<format>.",
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to YAML config (preset + overrides). Defaults to built-in default preset.",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(list(_VALID_FORMATS), case_sensitive=False),
+    default=None,
+    help="Output format. Inferred from --output extension if omitted.",
+)
+def convert_command(
+    input_path: Path,
+    output: Path | None,
+    config_path: Path | None,
+    fmt: str | None,
+) -> None:
+    """Convert INPUT markdown into the chosen format."""
+
+    resolved_fmt = _resolve_format(fmt, output)
+    if output is None:
+        output = input_path.with_suffix(f".{resolved_fmt}")
+
+    def _do() -> None:
+        config = _load_config(config_path)
+        markdown = input_path.read_text(encoding="utf-8")
+        storage = get_storage(default_base_dir=input_path.parent)
+        _LOGGER.debug(
+            "convert input=%s output=%s format=%s preset=%s",
+            input_path,
+            output,
+            resolved_fmt,
+            config.preset,
+        )
+        data = convert_pipeline(
+            markdown, config, format=resolved_fmt, storage=storage
+        )
+        assert output is not None
+        output.write_bytes(data)
+        click.echo(f"Wrote {output}")
+
+    _execute(_do)
+
+
+@cli.command("validate")
+@click.argument(
+    "input_path",
+    metavar="INPUT",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to YAML config (preset + overrides). Defaults to built-in default preset.",
+)
+def validate_command(input_path: Path, config_path: Path | None) -> None:
+    """Validate INPUT markdown + config without producing output."""
+
+    def _do() -> None:
+        config = _load_config(config_path)
+        markdown = input_path.read_text(encoding="utf-8")
+        from markdown_gost.render.bibliography import BibliographyIndex
+        from markdown_gost.render.references import prepare_document
+
+        document = prepare_document(parse_markdown(markdown), config)
+        BibliographyIndex.from_document(document, config)
+        click.echo(f"OK (preset={config.preset})")
+
+    _execute(_do)
+
+
+cli.add_command(import_command)
+
+
+if __name__ == "__main__":
+    cli()

markdown_gost-0.2.0/src/markdown_gost/cli/commands/import_cmd.py

@@ -0,0 +1,134 @@
+"""``markdown-gost import`` — конвертация DOCX/PDF → расширенный markdown.
+
+T036 ввёл docx-импорт; T041 добавил PDF через unoserver-prepass.
+
+Exit codes:
+
+* ``0`` — успех (даже если были fallbacks).
+* ``1`` — невалидный вход: файл не найден или расширение не ``.docx`` / ``.pdf``.
+* ``2`` — pandoc/unoserver упал на верхнем уровне.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import sys
+from pathlib import Path
+
+import click
+
+from markdown_gost.import_ import ImportContext, ImportResult, import_docx, import_pdf
+from markdown_gost.import_.metrics import IMPORT_TOTAL
+from markdown_gost.import_.pandoc_runner import PandocError
+from markdown_gost.output.pdf_writer import UnoserverError
+from markdown_gost.storage import get_storage
+
+_LOGGER = logging.getLogger("markdown_gost.cli.import")
+
+_HEADING_RE = re.compile(r"^#{1,6}\s")
+_TABLE_SEP_RE = re.compile(r"^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$")
+
+
+def _count_headings(markdown: str) -> int:
+    return sum(1 for line in markdown.splitlines() if _HEADING_RE.match(line))
+
+
+def _count_tables(markdown: str) -> int:
+    return sum(1 for line in markdown.splitlines() if _TABLE_SEP_RE.match(line))
+
+
+def _total_fallbacks(result: ImportResult) -> int:
+    return sum(result.fallbacks.values())
+
+
+@click.command("import")
+@click.argument("input_path", metavar="INPUT", type=click.Path(path_type=Path))
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Output markdown path. Defaults to <input-stem>.md рядом с input.",
+)
+@click.option(
+    "--images-dir",
+    "images_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Куда класть извлечённые картинки. По умолчанию <output-stem>_files/.",
+)
+def import_command(
+    input_path: Path,
+    output: Path | None,
+    images_dir: Path | None,
+) -> None:
+    """Импорт DOCX/PDF в расширенный markdown markdown_gost.
+
+    PDF-input идёт через unoserver-prepass (PDF → DOCX → md). Сканированные
+    PDF без текстового слоя возвращаются как пустой md без падения.
+    """
+    if not input_path.exists():
+        click.echo(f"Error: input not found: {input_path}", err=True)
+        sys.exit(1)
+
+    suffix = input_path.suffix.lower()
+    if suffix not in (".docx", ".pdf"):
+        click.echo(
+            f"Error: unsupported input extension {suffix!r}; expected .docx or .pdf",
+            err=True,
+        )
+        sys.exit(1)
+
+    if output is None:
+        output = input_path.with_suffix(".md")
+    if images_dir is None:
+        images_dir = output.with_name(f"{output.stem}_files")
+
+    storage = get_storage(default_base_dir=output.parent)
+    ctx = ImportContext(
+        storage=storage,
+        images_prefix=None,
+        images_dir=images_dir,
+    )
+    fmt_label = "pdf" if suffix == ".pdf" else "docx"
+
+    _LOGGER.info(
+        "import input=%s output=%s images_dir=%s format=%s",
+        input_path,
+        output,
+        images_dir,
+        fmt_label,
+    )
+
+    importer = import_pdf if suffix == ".pdf" else import_docx
+    try:
+        result = importer(input_path, ctx)
+    except (PandocError, UnoserverError) as exc:
+        IMPORT_TOTAL.labels(format=fmt_label, result="error").inc()
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(2)
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(result.markdown, encoding="utf-8")
+
+    if logging.getLogger().level <= logging.DEBUG and result.warnings:
+        for warning in result.warnings:
+            click.echo(f"warning: {warning}", err=True)
+
+    fallback_total = _total_fallbacks(result)
+    IMPORT_TOTAL.labels(format=fmt_label, result="success").inc()
+    if fallback_total > 0:
+        IMPORT_TOTAL.labels(format=fmt_label, result="fallback").inc()
+
+    click.echo(
+        "Imported: "
+        f"{_count_headings(result.markdown)} headings, "
+        f"{_count_tables(result.markdown)} tables, "
+        f"{len(result.images)} images, "
+        f"{fallback_total} fallbacks",
+        err=True,
+    )
+
+
+__all__ = ["import_command"]

markdown_gost-0.2.0/src/markdown_gost/config/errors.py

@@ -0,0 +1,8 @@
+class ConfigError(Exception):
+    """Base class for configuration loading errors."""
+
+
+class UnknownPresetError(ConfigError):
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Unknown preset: {name!r}")
+        self.name = name

markdown_gost-0.2.0/src/markdown_gost/config/loader.py

@@ -0,0 +1,59 @@
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from markdown_gost.config.errors import UnknownPresetError
+from markdown_gost.config.schema import Config
+
+
+def _deep_merge(base: dict[str, Any], overrides: dict[str, Any]) -> dict[str, Any]:
+    result: dict[str, Any] = dict(base)
+    for key, value in overrides.items():
+        existing = result.get(key)
+        if isinstance(existing, dict) and isinstance(value, dict):
+            result[key] = _deep_merge(existing, value)
+        else:
+            result[key] = value
+    return result
+
+
+def _load_preset(name: str) -> dict[str, Any]:
+    try:
+        text = (
+            resources.files("markdown_gost.config.presets")
+            .joinpath(f"{name}.yaml")
+            .read_text(encoding="utf-8")
+        )
+    except (FileNotFoundError, IsADirectoryError, ModuleNotFoundError) as e:
+        raise UnknownPresetError(name) from e
+    parsed = yaml.safe_load(text)
+    if parsed is None:
+        return {}
+    if not isinstance(parsed, dict):
+        raise UnknownPresetError(name)
+    return parsed
+
+
+def load_config_from_string(content: str) -> Config:
+    user = yaml.safe_load(content)
+    if not isinstance(user, dict):
+        return Config.model_validate(user if user is not None else {})
+
+    preset_name = user.get("preset")
+    if not isinstance(preset_name, str) or not preset_name:
+        return Config.model_validate(user)
+
+    preset_data = _load_preset(preset_name)
+    overrides = user.get("overrides") or {}
+    if not isinstance(overrides, dict):
+        return Config.model_validate({"preset": preset_name, "overrides": overrides})
+
+    merged = _deep_merge(preset_data, overrides)
+    merged["preset"] = preset_name
+    return Config.model_validate(merged)
+
+
+def load_config_from_path(path: Path) -> Config:
+    return load_config_from_string(path.read_text(encoding="utf-8"))