md-adf 0.1.0__tar.gz

md_adf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Markdown-ADF contributors
+
+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.

md_adf-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: md-adf
+Version: 0.1.0
+Summary: Markdown-ADF converter for Python.
+Author: Markdown-ADF contributors
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema<5.0.0,>=4.26.0
+Requires-Dist: mistune<4.0.0,>=3.2.1
+Dynamic: license-file
+
+# md-adf
+
+Typed Python implementation of the Markdown-ADF converter.
+
+## Install
+
+```sh
+pip install md-adf
+```
+
+Requires Python 3.10 or newer.
+
+## API
+
+```python
+from md_adf import (
+    adf_to_markdown,
+    markdown_to_adf,
+    parse_adf,
+    validate_adf,
+)
+
+markdown_result = adf_to_markdown(adf_document)
+print(markdown_result.value)
+print(markdown_result.diagnostics)
+
+adf_result = markdown_to_adf("## Hello\n\nThis is **ADF**.")
+print(adf_result.value)
+```
+
+Results have this shape:
+
+```python
+@dataclass(frozen=True)
+class ConversionResult(Generic[T]):
+    value: T
+    diagnostics: list[Diagnostic]
+```
+
+Current `ConversionOptions` support:
+
+- `markdown_dialect`: only `gfm` is supported; other values are rejected. Dict options may also use `markdownDialect`.
+- `profile`: `jira`, `confluence`, and `portableMarkdown` are accepted for API and CLI parity, but do not change Phase 1 conversion behavior yet.
+- `validate_adf`: defaults to `True`; set to `False` to skip pinned schema validation for ADF-to-Markdown input. Dict options may also use `validateAdf`.
+- `normalize_adf`: accepted for future normalization controls. It is currently a no-op because Phase 1 Markdown-to-ADF output is already normalized where supported. Dict options may also use `normalizeAdf`.
+
+ADF-to-Markdown returns a string with trailing whitespace trimmed and no final newline. The CLI writes that string exactly.
+
+## CLI
+
+```sh
+md-adf to-md input.adf.json --output output.md
+md-adf to-adf input.md --output output.adf.json
+md-adf validate-adf input.adf.json
+cat input.md | md-adf to-adf --profile jira
+```
+
+Supported profiles are `jira`, `confluence`, and `portableMarkdown`. Diagnostics are emitted as JSON lines to stderr.
+
+## Current Support
+
+- ADF validation/parsing against a pinned ADF schema.
+- ADF to Markdown for `doc`, `paragraph`, `heading`, `blockquote`, `bulletList`, `orderedList`, `listItem`, `codeBlock`, `rule`, simple GFM tables, task lists, media link/text fallback, rich inline text fallback for `mention`, `emoji`, `date`, and `status`, `text`, and `hardBreak`.
+- Markdown to ADF for paragraphs, headings, block quotes, lists, GFM task lists, code blocks, thematic breaks, GFM tables, text, hard breaks, soft breaks, links, images as link text fallback, and raw HTML as text fallback.
+- Marks for `strong`, `em`, `strike`, `code`, and `link`.
+- Structured diagnostics for invalid ADF roots, unsupported ADF nodes/marks, invalid containers, invalid link marks, complex table omission, task-list fallback, image/media fallback, rich inline fallback, and dropped rich inline attributes.
+
+## Known Limitations
+
+- ADF to Markdown only renders simple rectangular tables as GFM pipe tables; complex tables are omitted with diagnostics.
+- Media is represented as Markdown link/text fallback; no media URL resolver or image emission exists yet.
+- Markdown to ADF maps images to linked text fallback instead of ADF media nodes.
+- Mixed or complex GFM task lists may fall back to ordinary list items with diagnostics.
+- ADF to Markdown renders mentions, emoji, dates, and statuses as text fallbacks; Markdown to ADF keeps that text as normal text and does not recreate rich inline node IDs.
+- ADF to Markdown does not yet render panels, expands, cards, layout nodes, extensions, or color/underline/subscript/superscript marks.
+- Markdown raw HTML is preserved as text fallback; it is not interpreted into rich ADF.
+- Unsupported ADF nodes are omitted with diagnostics.
+- Markdown parser AST access is not exposed as public API yet; conversion uses real Markdown parsers internally.
+
+## Development
+
+```sh
+poetry -C packages/python run python ../../tools/conformance/run-python.py
+poetry -C packages/python run pytest
+poetry -C packages/python run ruff check --config ../../pyproject.toml src tests ../../tools/conformance/run-python.py
+poetry -C packages/python run mypy --config-file ../../pyproject.toml src tests ../../tools/conformance/run-python.py
+npm run test:packages
+```
+
+Shared conformance fixtures live in `../../fixtures` and are run by the root `just test-python` command.

md_adf-0.1.0/README.md

@@ -0,0 +1,90 @@
+# md-adf
+
+Typed Python implementation of the Markdown-ADF converter.
+
+## Install
+
+```sh
+pip install md-adf
+```
+
+Requires Python 3.10 or newer.
+
+## API
+
+```python
+from md_adf import (
+    adf_to_markdown,
+    markdown_to_adf,
+    parse_adf,
+    validate_adf,
+)
+
+markdown_result = adf_to_markdown(adf_document)
+print(markdown_result.value)
+print(markdown_result.diagnostics)
+
+adf_result = markdown_to_adf("## Hello\n\nThis is **ADF**.")
+print(adf_result.value)
+```
+
+Results have this shape:
+
+```python
+@dataclass(frozen=True)
+class ConversionResult(Generic[T]):
+    value: T
+    diagnostics: list[Diagnostic]
+```
+
+Current `ConversionOptions` support:
+
+- `markdown_dialect`: only `gfm` is supported; other values are rejected. Dict options may also use `markdownDialect`.
+- `profile`: `jira`, `confluence`, and `portableMarkdown` are accepted for API and CLI parity, but do not change Phase 1 conversion behavior yet.
+- `validate_adf`: defaults to `True`; set to `False` to skip pinned schema validation for ADF-to-Markdown input. Dict options may also use `validateAdf`.
+- `normalize_adf`: accepted for future normalization controls. It is currently a no-op because Phase 1 Markdown-to-ADF output is already normalized where supported. Dict options may also use `normalizeAdf`.
+
+ADF-to-Markdown returns a string with trailing whitespace trimmed and no final newline. The CLI writes that string exactly.
+
+## CLI
+
+```sh
+md-adf to-md input.adf.json --output output.md
+md-adf to-adf input.md --output output.adf.json
+md-adf validate-adf input.adf.json
+cat input.md | md-adf to-adf --profile jira
+```
+
+Supported profiles are `jira`, `confluence`, and `portableMarkdown`. Diagnostics are emitted as JSON lines to stderr.
+
+## Current Support
+
+- ADF validation/parsing against a pinned ADF schema.
+- ADF to Markdown for `doc`, `paragraph`, `heading`, `blockquote`, `bulletList`, `orderedList`, `listItem`, `codeBlock`, `rule`, simple GFM tables, task lists, media link/text fallback, rich inline text fallback for `mention`, `emoji`, `date`, and `status`, `text`, and `hardBreak`.
+- Markdown to ADF for paragraphs, headings, block quotes, lists, GFM task lists, code blocks, thematic breaks, GFM tables, text, hard breaks, soft breaks, links, images as link text fallback, and raw HTML as text fallback.
+- Marks for `strong`, `em`, `strike`, `code`, and `link`.
+- Structured diagnostics for invalid ADF roots, unsupported ADF nodes/marks, invalid containers, invalid link marks, complex table omission, task-list fallback, image/media fallback, rich inline fallback, and dropped rich inline attributes.
+
+## Known Limitations
+
+- ADF to Markdown only renders simple rectangular tables as GFM pipe tables; complex tables are omitted with diagnostics.
+- Media is represented as Markdown link/text fallback; no media URL resolver or image emission exists yet.
+- Markdown to ADF maps images to linked text fallback instead of ADF media nodes.
+- Mixed or complex GFM task lists may fall back to ordinary list items with diagnostics.
+- ADF to Markdown renders mentions, emoji, dates, and statuses as text fallbacks; Markdown to ADF keeps that text as normal text and does not recreate rich inline node IDs.
+- ADF to Markdown does not yet render panels, expands, cards, layout nodes, extensions, or color/underline/subscript/superscript marks.
+- Markdown raw HTML is preserved as text fallback; it is not interpreted into rich ADF.
+- Unsupported ADF nodes are omitted with diagnostics.
+- Markdown parser AST access is not exposed as public API yet; conversion uses real Markdown parsers internally.
+
+## Development
+
+```sh
+poetry -C packages/python run python ../../tools/conformance/run-python.py
+poetry -C packages/python run pytest
+poetry -C packages/python run ruff check --config ../../pyproject.toml src tests ../../tools/conformance/run-python.py
+poetry -C packages/python run mypy --config-file ../../pyproject.toml src tests ../../tools/conformance/run-python.py
+npm run test:packages
+```
+
+Shared conformance fixtures live in `../../fixtures` and are run by the root `just test-python` command.

md_adf-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "md-adf"
+version = "0.1.0"
+description = "Markdown-ADF converter for Python."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Markdown-ADF contributors" }
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed"
+]
+dependencies = [
+  "jsonschema>=4.26.0,<5.0.0",
+  "mistune>=3.2.1,<4.0.0"
+]
+
+[project.scripts]
+md-adf = "md_adf_cli.__main__:main"
+
+[tool.poetry.group.dev.dependencies]
+mypy = ">=1.0"
+pytest = ">=8.0"
+ruff = ">=0.4"
+types-jsonschema = "^4.26.0.20260408"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["md_adf*", "md_adf_cli*"]
+
+[tool.setuptools.package-data]
+md_adf = ["py.typed", "schemas/*.json"]

md_adf-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

md_adf-0.1.0/src/md_adf/__init__.py

@@ -0,0 +1,16 @@
+"""Markdown-ADF converter package."""
+
+from .adf.validate import parse_adf, validate_adf
+from .convert.adf_to_markdown import adf_to_markdown
+from .convert.markdown_to_adf import markdown_to_adf
+from .options import ConversionOptions, ConversionOptionsInput, ConversionResult
+
+__all__ = [
+    "ConversionResult",
+    "ConversionOptions",
+    "ConversionOptionsInput",
+    "adf_to_markdown",
+    "markdown_to_adf",
+    "parse_adf",
+    "validate_adf",
+]

md_adf-0.1.0/src/md_adf/adf/__init__.py

@@ -0,0 +1,4 @@
+from .types import AdfDocument, AdfNode
+from .validate import ValidationResult, parse_adf, validate_adf
+
+__all__ = ["AdfDocument", "AdfNode", "ValidationResult", "parse_adf", "validate_adf"]

md_adf-0.1.0/src/md_adf/adf/normalize.py

@@ -0,0 +1 @@
+"""ADF normalization placeholder."""

md_adf-0.1.0/src/md_adf/adf/types.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class AdfNode(TypedDict, total=False):
+    """Minimal structural representation for ADF nodes used by the converters."""
+
+    type: str
+    attrs: dict[str, Any]
+    marks: list[dict[str, Any]]
+    content: list["AdfNode"]
+    text: str
+
+
+class AdfDocument(TypedDict):
+    """Root ADF document shape accepted and emitted by this package."""
+
+    version: int
+    type: str
+    content: list[AdfNode]

md_adf-0.1.0/src/md_adf/adf/validate.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+from pathlib import Path
+from typing import Any, cast
+
+from jsonschema import Draft4Validator
+from jsonschema.exceptions import ValidationError
+
+from .types import AdfDocument
+
+
+@dataclass(frozen=True)
+class ParseAdfOptions:
+    """Options controlling how unknown values are parsed as ADF."""
+
+    validate_adf: bool = True
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """Structured success/error result for ADF validation."""
+
+    valid: bool
+    errors: list[str] = field(default_factory=list)
+
+
+def parse_adf(value: Any, options: Any = None) -> AdfDocument:
+    """Parse an unknown value as an ADF document, optionally validating schema."""
+
+    if (
+        isinstance(value, dict)
+        and value.get("version") == 1
+        and value.get("type") == "doc"
+        and isinstance(value.get("content"), list)
+    ):
+        if _validate_enabled(options):
+            errors = list(_VALIDATOR.iter_errors(value))
+            if errors:
+                raise ValueError(_format_schema_error(_most_specific_error(errors, value)))
+        return cast(AdfDocument, value)
+
+    raise ValueError("Invalid ADF root: expected doc version 1.")
+
+
+def validate_adf(value: Any, options: Any = None) -> ValidationResult:
+    """Validate an unknown value as ADF without raising validation errors."""
+
+    try:
+        parse_adf(value, options)
+    except ValueError as exc:
+        return ValidationResult(valid=False, errors=[str(exc)])
+
+    return ValidationResult(valid=True)
+
+
+def _schema_path() -> Path:
+    """Find the pinned ADF JSON Schema in source or packaged layouts."""
+
+    here = Path(__file__).resolve()
+    candidates = [
+        here.parents[1] / "schemas" / "adf-schema.json",
+        here.parents[5] / "schemas" / "adf-schema.json",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    raise RuntimeError("Pinned ADF JSON Schema not found.")
+
+
+_SCHEMA = json.loads(_schema_path().read_text(encoding="utf-8"))
+_VALIDATOR = Draft4Validator(_SCHEMA)
+
+
+def _validate_enabled(options: Any) -> bool:
+    """Read the validate_adf option from dataclass or mapping-style options."""
+
+    if options is None:
+        return True
+    if isinstance(options, ParseAdfOptions):
+        return options.validate_adf
+    if hasattr(options, "validate_adf"):
+        return bool(options.validate_adf)
+    value = options.get("validate_adf", options.get("validateAdf", True))
+    return bool(value)
+
+
+def _format_schema_error(error: ValidationError) -> str:
+    """Convert a jsonschema validation error into a concise user message."""
+
+    path = _json_pointer(error.absolute_path)
+    location = f" at {path}" if path else ""
+
+    if error.validator == "required":
+        missing = _required_property(error.message)
+        return f"Invalid ADF{location}: missing required property '{missing}'."
+    if error.validator == "additionalProperties":
+        property_name = _additional_property(error.message)
+        return f"Invalid ADF{location}: unexpected property '{property_name}'."
+    if error.validator == "enum":
+        return f"Invalid ADF{location}: value is not allowed."
+    if error.validator == "type":
+        return f"Invalid ADF{location}: expected {error.validator_value}."
+    if error.validator == "minLength":
+        return f"Invalid ADF{location}: expected a non-empty string."
+    if error.validator == "minItems":
+        return f"Invalid ADF{location}: expected at least one item."
+    return f"Invalid ADF{location}: failed schema constraint '{error.validator}'."
+
+
+def _most_specific_error(errors: list[ValidationError], value: Any) -> ValidationError:
+    """Choose the schema error that best identifies the invalid ADF location."""
+
+    candidates = _leaf_errors(errors)
+    relevant = [error for error in candidates if error.validator not in {"anyOf", "oneOf"}]
+    matching_type_error = next(
+        (error for error in relevant if _error_matches_actual_type(error, value)),
+        None,
+    )
+    if matching_type_error is not None:
+        return matching_type_error
+    return max(relevant or candidates, key=_error_specificity)
+
+
+def _leaf_errors(errors: list[ValidationError]) -> list[ValidationError]:
+    """Flatten nested anyOf/oneOf validation contexts to leaf errors."""
+
+    leaves: list[ValidationError] = []
+    for error in errors:
+        if error.context:
+            leaves.extend(_leaf_errors(list(error.context)))
+        else:
+            leaves.append(error)
+    return leaves
+
+
+def _json_pointer(path: Any) -> str:
+    """Render a jsonschema path as an escaped JSON Pointer."""
+
+    parts = [str(part).replace("~", "~0").replace("/", "~1") for part in path]
+    return "/" + "/".join(parts) if parts else ""
+
+
+def _error_specificity(error: ValidationError) -> int:
+    """Score schema errors so deeper paths are considered more specific."""
+
+    base = len(error.absolute_path)
+    if error.validator == "required" and "/attrs" in _json_pointer(error.absolute_path):
+        return base + 1
+    return base
+
+
+def _additional_property(message: str) -> str:
+    """Extract an additional-property name from a jsonschema error message."""
+
+    marker = "'"
+    start = message.find(marker)
+    end = message.find(marker, start + 1)
+    return message[start + 1 : end] if start >= 0 and end > start else "unknown"
+
+
+def _error_matches_actual_type(error: ValidationError, value: Any) -> bool:
+    """Check whether a required-property error matches the node's actual type."""
+
+    if error.validator != "required":
+        return False
+
+    parent_path = list(error.absolute_path)
+    if parent_path[-1:] == ["attrs"]:
+        parent_path = parent_path[:-1]
+    parent = _value_at_path(value, parent_path)
+    if (
+        isinstance(parent, dict)
+        and parent.get("type") == "link"
+        and _required_property(error.message) == "href"
+    ):
+        return True
+
+    schema_path = list(error.schema_path)
+    if len(schema_path) < 2 or schema_path[0] != "definitions":
+        return False
+
+    definition = str(schema_path[1])
+    expected_type = definition.removesuffix("_mark").removesuffix("_node")
+    return isinstance(parent, dict) and parent.get("type") == expected_type
+
+
+def _value_at_path(value: Any, path: list[Any]) -> Any:
+    """Resolve a jsonschema path against a nested Python value."""
+
+    current = value
+    for part in path:
+        if isinstance(current, list) and isinstance(part, int):
+            current = current[part]
+        elif isinstance(current, dict):
+            current = current.get(part)
+        else:
+            return None
+    return current
+
+
+def _required_property(message: str) -> str:
+    """Extract a required-property name from a jsonschema error message."""
+
+    marker = "'"
+    start = message.find(marker)
+    end = message.find(marker, start + 1)
+    return message[start + 1 : end] if start >= 0 and end > start else "unknown"

md_adf-0.1.0/src/md_adf/convert/__init__.py

@@ -0,0 +1,4 @@
+from .adf_to_markdown import adf_to_markdown
+from .markdown_to_adf import markdown_to_adf
+
+__all__ = ["adf_to_markdown", "markdown_to_adf"]