adflux 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. adflux-0.1.0/.gitignore +267 -0
  2. adflux-0.1.0/CHANGELOG.md +27 -0
  3. adflux-0.1.0/LICENSE +21 -0
  4. adflux-0.1.0/PKG-INFO +209 -0
  5. adflux-0.1.0/README.md +164 -0
  6. adflux-0.1.0/docs/architecture.md +74 -0
  7. adflux-0.1.0/docs/design.md +179 -0
  8. adflux-0.1.0/docs/e2e-testing.md +116 -0
  9. adflux-0.1.0/docs/extending.md +62 -0
  10. adflux-0.1.0/docs/fidelity-matrix.md +58 -0
  11. adflux-0.1.0/docs/profiles.md +75 -0
  12. adflux-0.1.0/docs/usage.md +116 -0
  13. adflux-0.1.0/examples/README.md +24 -0
  14. adflux-0.1.0/examples/adf_to_markdown.py +35 -0
  15. adflux-0.1.0/examples/confluence_roundtrip.py +43 -0
  16. adflux-0.1.0/examples/extensions.md +26 -0
  17. adflux-0.1.0/examples/md_to_adf.py +29 -0
  18. adflux-0.1.0/examples/sample.adf.json +88 -0
  19. adflux-0.1.0/pyproject.toml +204 -0
  20. adflux-0.1.0/src/adflux/__init__.py +25 -0
  21. adflux-0.1.0/src/adflux/api.py +82 -0
  22. adflux-0.1.0/src/adflux/cli.py +129 -0
  23. adflux-0.1.0/src/adflux/errors.py +55 -0
  24. adflux-0.1.0/src/adflux/formats/__init__.py +74 -0
  25. adflux-0.1.0/src/adflux/formats/adf/__init__.py +15 -0
  26. adflux-0.1.0/src/adflux/formats/adf/mapping.py +137 -0
  27. adflux-0.1.0/src/adflux/formats/adf/mapping.yaml +233 -0
  28. adflux-0.1.0/src/adflux/formats/adf/reader.py +268 -0
  29. adflux-0.1.0/src/adflux/formats/adf/schema/adf-minimal.schema.json +45 -0
  30. adflux-0.1.0/src/adflux/formats/adf/schema.py +77 -0
  31. adflux-0.1.0/src/adflux/formats/adf/writer.py +325 -0
  32. adflux-0.1.0/src/adflux/formats/markdown/__init__.py +59 -0
  33. adflux-0.1.0/src/adflux/formats/markdown/pretty.py +757 -0
  34. adflux-0.1.0/src/adflux/formats/markdown/reader.py +352 -0
  35. adflux-0.1.0/src/adflux/formats/markdown/writer.py +333 -0
  36. adflux-0.1.0/src/adflux/ir/__init__.py +27 -0
  37. adflux-0.1.0/src/adflux/ir/envelope.py +177 -0
  38. adflux-0.1.0/src/adflux/ir/profile_filter.py +54 -0
  39. adflux-0.1.0/src/adflux/logging.py +54 -0
  40. adflux-0.1.0/src/adflux/profiles.py +82 -0
  41. adflux-0.1.0/tests/conftest.py +13 -0
  42. adflux-0.1.0/tests/e2e/__init__.py +15 -0
  43. adflux-0.1.0/tests/e2e/compare.py +126 -0
  44. adflux-0.1.0/tests/e2e/confluence_client.py +144 -0
  45. adflux-0.1.0/tests/e2e/conftest.py +224 -0
  46. adflux-0.1.0/tests/e2e/jira_client.py +135 -0
  47. adflux-0.1.0/tests/e2e/test_confluence_roundtrip.py +315 -0
  48. adflux-0.1.0/tests/e2e/test_jira_roundtrip.py +111 -0
  49. adflux-0.1.0/tests/integration/__init__.py +0 -0
  50. adflux-0.1.0/tests/integration/test_end_to_end.py +61 -0
  51. adflux-0.1.0/tests/roundtrip/__init__.py +0 -0
  52. adflux-0.1.0/tests/roundtrip/test_adf_property.py +63 -0
  53. adflux-0.1.0/tests/roundtrip/test_adf_roundtrip.py +95 -0
  54. adflux-0.1.0/tests/roundtrip/test_node_coverage.py +225 -0
  55. adflux-0.1.0/tests/roundtrip/test_table_roundtrip.py +69 -0
  56. adflux-0.1.0/tests/unit/__init__.py +0 -0
  57. adflux-0.1.0/tests/unit/test_adf_reader.py +180 -0
  58. adflux-0.1.0/tests/unit/test_adf_schema.py +53 -0
  59. adflux-0.1.0/tests/unit/test_adf_writer.py +89 -0
  60. adflux-0.1.0/tests/unit/test_envelope.py +101 -0
  61. adflux-0.1.0/tests/unit/test_mapping_loader.py +62 -0
  62. adflux-0.1.0/tests/unit/test_profile_filter.py +86 -0
  63. adflux-0.1.0/tests/unit/test_profiles.py +48 -0
@@ -0,0 +1,267 @@
1
+ ### Base Template
2
+ # This template covers universal patterns only. Language and framework-specific
3
+ # patterns should be appended to this template based on specific project needs:
4
+ # https://github.com/github/gitignore
5
+
6
+ # Agent and Developer Temporary Files
7
+ .tmp/
8
+
9
+ # Environment and Secrets
10
+ .env
11
+ .env.*
12
+ !.env.example
13
+
14
+ # OS-Generated Files
15
+ Thumbs.db
16
+ Desktop.ini
17
+ .DS_Store
18
+ ._*
19
+
20
+ # Editor and IDE
21
+ *.swp
22
+ *.swo
23
+ *~
24
+ .idea/
25
+ *.iml
26
+ .vscode/*
27
+ !.vscode/settings.json
28
+ !.vscode/tasks.json
29
+ !.vscode/launch.json
30
+ !.vscode/extensions.json
31
+ *.code-workspace
32
+
33
+ # Build Artifacts
34
+ dist/
35
+ build/
36
+ out/
37
+
38
+ ### Python Template
39
+ # Byte-compiled / optimized / DLL files
40
+ __pycache__/
41
+ *.py[codz]
42
+ *$py.class
43
+
44
+ # C extensions
45
+ *.so
46
+
47
+ # Distribution / packaging
48
+ .Python
49
+ build/
50
+ develop-eggs/
51
+ dist/
52
+ downloads/
53
+ eggs/
54
+ .eggs/
55
+ lib/
56
+ lib64/
57
+ parts/
58
+ sdist/
59
+ var/
60
+ wheels/
61
+ share/python-wheels/
62
+ *.egg-info/
63
+ .installed.cfg
64
+ *.egg
65
+ MANIFEST
66
+
67
+ # PyInstaller
68
+ # Usually these files are written by a python script from a template
69
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
70
+ *.manifest
71
+ *.spec
72
+
73
+ # Installer logs
74
+ pip-log.txt
75
+ pip-delete-this-directory.txt
76
+
77
+ # Unit test / coverage reports
78
+ htmlcov/
79
+ .tox/
80
+ .nox/
81
+ .coverage
82
+ .coverage.*
83
+ .cache
84
+ nosetests.xml
85
+ coverage.xml
86
+ *.cover
87
+ *.py.cover
88
+ .hypothesis/
89
+ .pytest_cache/
90
+ cover/
91
+
92
+ # Translations
93
+ *.mo
94
+ *.pot
95
+
96
+ # Django stuff:
97
+ *.log
98
+ local_settings.py
99
+ db.sqlite3
100
+ db.sqlite3-journal
101
+
102
+ # Flask stuff:
103
+ instance/
104
+ .webassets-cache
105
+
106
+ # Scrapy stuff:
107
+ .scrapy
108
+
109
+ # Sphinx documentation
110
+ docs/_build/
111
+
112
+ # PyBuilder
113
+ .pybuilder/
114
+ target/
115
+
116
+ # Jupyter Notebook
117
+ .ipynb_checkpoints
118
+
119
+ # IPython
120
+ profile_default/
121
+ ipython_config.py
122
+
123
+ # pyenv
124
+ # For a library or package, you might want to ignore these files since the code is
125
+ # intended to run in multiple environments; otherwise, check them in:
126
+ # .python-version
127
+
128
+ # pipenv
129
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
130
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
131
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
132
+ # install all needed dependencies.
133
+ # Pipfile.lock
134
+
135
+ # UV
136
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
137
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
138
+ # commonly ignored for libraries.
139
+ # uv.lock
140
+
141
+ # poetry
142
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
143
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
144
+ # commonly ignored for libraries.
145
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
146
+ # poetry.lock
147
+ # poetry.toml
148
+
149
+ # pdm
150
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
151
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
152
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
153
+ # pdm.lock
154
+ # pdm.toml
155
+ .pdm-python
156
+ .pdm-build/
157
+
158
+ # pixi
159
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
160
+ # pixi.lock
161
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
162
+ # in the .venv directory. It is recommended not to include this directory in version control.
163
+ .pixi
164
+
165
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
166
+ __pypackages__/
167
+
168
+ # Celery stuff
169
+ celerybeat-schedule
170
+ celerybeat.pid
171
+
172
+ # Redis
173
+ *.rdb
174
+ *.aof
175
+ *.pid
176
+
177
+ # RabbitMQ
178
+ mnesia/
179
+ rabbitmq/
180
+ rabbitmq-data/
181
+
182
+ # ActiveMQ
183
+ activemq-data/
184
+
185
+ # SageMath parsed files
186
+ *.sage.py
187
+
188
+ # Environments
189
+ .env
190
+ .envrc
191
+ .venv
192
+ env/
193
+ venv/
194
+ ENV/
195
+ env.bak/
196
+ venv.bak/
197
+
198
+ # Spyder project settings
199
+ .spyderproject
200
+ .spyproject
201
+
202
+ # Rope project settings
203
+ .ropeproject
204
+
205
+ # mkdocs documentation
206
+ /site
207
+
208
+ # mypy
209
+ .mypy_cache/
210
+ .dmypy.json
211
+ dmypy.json
212
+
213
+ # Pyre type checker
214
+ .pyre/
215
+
216
+ # pytype static type analyzer
217
+ .pytype/
218
+
219
+ # Cython debug symbols
220
+ cython_debug/
221
+
222
+ # PyCharm
223
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
224
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
225
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
226
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
227
+ # .idea/
228
+
229
+ # Abstra
230
+ # Abstra is an AI-powered process automation framework.
231
+ # Ignore directories containing user credentials, local state, and settings.
232
+ # Learn more at https://abstra.io/docs
233
+ .abstra/
234
+
235
+ # Visual Studio Code
236
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
237
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
238
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
239
+ # you could uncomment the following to ignore the entire vscode folder
240
+ # .vscode/
241
+ # Temporary file for partial code execution
242
+ tempCodeRunnerFile.py
243
+
244
+ # Ruff stuff:
245
+ .ruff_cache/
246
+
247
+ # PyPI configuration file
248
+ .pypirc
249
+
250
+ # Marimo
251
+ marimo/_static/
252
+ marimo/_lsp/
253
+ __marimo__/
254
+
255
+ # Streamlit
256
+ .streamlit/secrets.toml
257
+
258
+ ### Project-Specific Rules
259
+ # Test artifacts produced by pytest --junitxml / coverage uploads.
260
+ junit.xml
261
+ junit-*.xml
262
+
263
+ # Local scratch / diff files used during development.
264
+ diff.txt
265
+
266
+ # Re-allow the env template (overrides base-template `.env.*` ignore).
267
+ !.env.example
@@ -0,0 +1,27 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+ Releases are produced automatically from
8
+ [Conventional Commits](https://www.conventionalcommits.org/) by
9
+ `go-semantic-release` — see [`.github/workflows/release.yml`](.github/workflows/release.yml).
10
+
11
+ ## [Unreleased]
12
+
13
+ ### Added
14
+ - Initial public release.
15
+ - Pure-Python **Markdown (CommonMark + GFM)** reader (via `markdown-it-py`) and
16
+ writer (hand-rolled CommonMark+GFM serializer).
17
+ - Custom bidirectional bridge for **Atlassian Document Format (ADF)** driven by
18
+ a declarative `mapping.yaml` (22+ node types).
19
+ - Lossless envelope convention (`Div`/`Span` with `adf-*` classes plus a
20
+ base64-JSON blob attribute) and a universal `adf-raw` fallback.
21
+ - Three fidelity profiles: `strict-adf`, `pretty-md`, `fail-loud`.
22
+ - Markdown writer renders ADF macros as **idiomatic Markdown** (GitHub
23
+ alerts, `<details>`, autolinks, GFM task lists) with HTML-comment
24
+ markers as a fallback, while preserving lossless `MD ↔ ADF` round-trips.
25
+ - ADF JSON Schema validation on read and write.
26
+ - Typer-based CLI (`adflux convert`, `validate`, `inspect-ast`, `list-formats`).
27
+ - 90+ unit, integration, round-trip, and property-based tests.
adflux-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mike Hill
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
adflux-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,209 @@
1
+ Metadata-Version: 2.4
2
+ Name: adflux
3
+ Version: 0.1.0
4
+ Summary: Pure-Python Markdown ↔ Atlassian Document Format (ADF) converter with lossless round-tripping
5
+ Project-URL: Homepage, https://github.com/mikejhill/adflux
6
+ Project-URL: Documentation, https://github.com/mikejhill/adflux/tree/main/docs
7
+ Project-URL: Repository, https://github.com/mikejhill/adflux
8
+ Project-URL: Issues, https://github.com/mikejhill/adflux/issues
9
+ Project-URL: Changelog, https://github.com/mikejhill/adflux/blob/main/CHANGELOG.md
10
+ Author-email: Mike Hill <mike@mikejhill.com>
11
+ Maintainer-email: Mike Hill <mike@mikejhill.com>
12
+ License: MIT
13
+ License-File: LICENSE
14
+ Keywords: adf,atlassian,atlassian-document-format,commonmark,confluence,converter,document-conversion,gfm,jira,markdown
15
+ Classifier: Development Status :: 4 - Beta
16
+ Classifier: Environment :: Console
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: Intended Audience :: Information Technology
19
+ Classifier: License :: OSI Approved :: MIT License
20
+ Classifier: Operating System :: MacOS
21
+ Classifier: Operating System :: Microsoft :: Windows
22
+ Classifier: Operating System :: OS Independent
23
+ Classifier: Operating System :: POSIX :: Linux
24
+ Classifier: Programming Language :: Python
25
+ Classifier: Programming Language :: Python :: 3
26
+ Classifier: Programming Language :: Python :: 3.11
27
+ Classifier: Programming Language :: Python :: 3.12
28
+ Classifier: Programming Language :: Python :: 3.13
29
+ Classifier: Programming Language :: Python :: Implementation :: CPython
30
+ Classifier: Topic :: Documentation
31
+ Classifier: Topic :: Software Development :: Documentation
32
+ Classifier: Topic :: Text Processing :: Markup
33
+ Classifier: Topic :: Text Processing :: Markup :: Markdown
34
+ Classifier: Topic :: Utilities
35
+ Classifier: Typing :: Typed
36
+ Requires-Python: >=3.11
37
+ Requires-Dist: jsonschema>=4.21
38
+ Requires-Dist: markdown-it-py>=3.0
39
+ Requires-Dist: mdit-py-plugins>=0.4
40
+ Requires-Dist: panflute>=2.3.1
41
+ Requires-Dist: pyyaml>=6.0
42
+ Requires-Dist: structlog>=24.1
43
+ Requires-Dist: typer>=0.12
44
+ Description-Content-Type: text/markdown
45
+
46
+ # adflux
47
+
48
+ [![CI](https://github.com/mikejhill/adflux/actions/workflows/ci.yml/badge.svg)](https://github.com/mikejhill/adflux/actions/workflows/ci.yml)
49
+ [![Release](https://github.com/mikejhill/adflux/actions/workflows/release.yml/badge.svg)](https://github.com/mikejhill/adflux/actions/workflows/release.yml)
50
+ [![PyPI](https://img.shields.io/pypi/v/adflux.svg)](https://pypi.org/project/adflux/)
51
+ [![Python](https://img.shields.io/pypi/pyversions/adflux.svg)](https://pypi.org/project/adflux/)
52
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
53
+
54
+ A pure-Python converter between Markdown (CommonMark + GFM) and Atlassian
55
+ Document Format (ADF) — the JSON document model used by Confluence and
56
+ Jira. Round-trips losslessly, including ADF-only constructs like panels,
57
+ status badges, mentions, task lists, expand sections, and macros.
58
+
59
+ ```mermaid
60
+ flowchart LR
61
+ MD[Markdown] -->|markdown-it-py| IR((Internal IR + adf-* envelopes))
62
+ ADF[ADF JSON] -->|mapping.yaml| IR
63
+ IR -->|profile filter| W{writer}
64
+ W -->|CommonMark serializer| MD2[Markdown]
65
+ W -->|mapping.yaml| ADF2[ADF JSON]
66
+ ```
67
+
68
+ ## Why adflux
69
+
70
+ ADF is JSON, but no mature pure-Python tool converts it to and from
71
+ Markdown without losing information. `adflux` fills that gap:
72
+
73
+ - **No system dependencies.** `pip install adflux` — no Pandoc binary,
74
+ no Node, no Ruby.
75
+ - **Lossless ADF round-trips.** A declarative `mapping.yaml` plus a small
76
+ envelope convention round-trips every ADF construct, including ones
77
+ the library has never seen.
78
+ - **Idiomatic Markdown output.** Panels become GitHub alert blockquotes,
79
+ expand sections become `<details>`, smart cards become autolinks. The
80
+ output looks correct in GitHub, VS Code, and any standard viewer.
81
+ - **Fidelity profiles** make lossy / lossless behavior explicit and
82
+ selectable per call.
83
+
84
+ ## Install
85
+
86
+ ```bash
87
+ pip install adflux
88
+ ```
89
+
90
+ Requires Python ≥ 3.11. Linux, macOS, and Windows are CI-tested.
91
+
92
+ ## Quick start
93
+
94
+ ```python
95
+ from adflux import convert
96
+
97
+ # Markdown → ADF JSON
98
+ adf = convert(open("README.md").read(), src="md", dst="adf")
99
+
100
+ # ADF JSON → Markdown, dropping ADF-only constructs to plain content
101
+ md = convert(adf, src="adf", dst="md", profile="pretty-md")
102
+ ```
103
+
104
+ ```bash
105
+ adflux convert --from md --to adf README.md > readme.adf.json
106
+ adflux convert --from adf --to md page.json
107
+ adflux validate page.adf.json
108
+ ```
109
+
110
+ Full API and CLI reference: [`docs/usage.md`](docs/usage.md).
111
+
112
+ ## Fidelity profiles
113
+
114
+ | Profile | Behavior on lossy targets |
115
+ | ------------ | --------------------------------------------------------------- |
116
+ | `strict-adf` | Preserve every ADF construct (default). Round-trips losslessly. |
117
+ | `pretty-md` | Drop ADF-only envelopes silently; keep their visible content. |
118
+ | `fail-loud` | Raise `UnrepresentableNodeError` on the first envelope. |
119
+
120
+ Worked examples: [`docs/profiles.md`](docs/profiles.md).
121
+
122
+ ## Markdown rendering of ADF constructs
123
+
124
+ | ADF construct | Rendered as |
125
+ | ---------------------------------------- | ---------------------------------------------------- |
126
+ | `panel` (info/note/warning/…) | GitHub alert blockquote (`> [!NOTE]`, `> [!TIP]`, …) |
127
+ | `expand` | `<details><summary>title</summary>…</details>` |
128
+ | `inlineCard` / `blockCard` / `embedCard` | Autolink (`<https://…>`) |
129
+ | `taskList` / `taskItem` | GFM task list (`- [ ]`, `- [x]`) |
130
+ | `emoji`, `mention` | Plain text (`🚀`, `@alice`) |
131
+ | Everything else | HTML-comment marker (`<!--adf:status …-->`) |
132
+
133
+ The reader recognises every form on its way back, so `MD → ADF → MD` is
134
+ stable.
135
+
136
+ ## How it works
137
+
138
+ - **IR**: an in-memory document tree built on
139
+ [panflute](https://github.com/sergiocorreia/panflute) AST classes
140
+ (used purely as Python data structures — no Pandoc binary involved),
141
+ with `Div` / `Span` envelopes for ADF-only constructs.
142
+ - **Envelopes**: class prefix `adf-<nodeType>` plus a base64-JSON blob
143
+ for complex attributes. A universal `adf-raw` fallback guarantees zero
144
+ data loss.
145
+ - **Mapping**: every ADF node type is described in
146
+ [`src/adflux/formats/adf/mapping.yaml`](src/adflux/formats/adf/mapping.yaml).
147
+ Adding a new node type is a YAML edit.
148
+
149
+ Deeper dives:
150
+ [`docs/design.md`](docs/design.md) ·
151
+ [`docs/architecture.md`](docs/architecture.md) ·
152
+ [`docs/profiles.md`](docs/profiles.md) ·
153
+ [`docs/fidelity-matrix.md`](docs/fidelity-matrix.md) ·
154
+ [`docs/extending.md`](docs/extending.md) ·
155
+ [`docs/e2e-testing.md`](docs/e2e-testing.md).
156
+
157
+ ## Examples
158
+
159
+ Runnable scripts in [`examples/`](examples):
160
+
161
+ ```bash
162
+ python examples/md_to_adf.py README.md
163
+ python examples/adf_to_markdown.py
164
+ python examples/confluence_roundtrip.py
165
+ ```
166
+
167
+ ## Development
168
+
169
+ ```bash
170
+ git clone https://github.com/mikejhill/adflux
171
+ cd adflux
172
+ uv sync --all-groups
173
+ uv run poe check
174
+ ```
175
+
176
+ Common tasks via [poethepoet](https://poethepoet.natn.io/):
177
+
178
+ ```bash
179
+ poe test # unit + integration + round-trip + property tests
180
+ poe test-e2e # live Confluence + Jira round-trip suite (requires .env)
181
+ poe lint # ruff format --check + ruff check
182
+ poe typecheck # ty check src
183
+ poe cov # pytest with coverage report
184
+ poe check # lint + typecheck + test (run before opening a PR)
185
+ poe build # sdist + wheel into ./dist
186
+ ```
187
+
188
+ CI runs the full matrix on Linux, macOS, and Windows for Python 3.11–3.13.
189
+
190
+ ## Releasing
191
+
192
+ Releases are automated. Land changes on `main` using
193
+ [Conventional Commits](https://www.conventionalcommits.org/), then run
194
+ the **Release** workflow from the GitHub Actions tab. `go-semantic-release`
195
+ computes the next version, builds the sdist + wheel, creates a tagged
196
+ GitHub Release, and publishes to PyPI via OIDC trusted publishing.
197
+
198
+ ## Contributing
199
+
200
+ Issues and pull requests are welcome. Before opening a PR:
201
+
202
+ 1. `poe check` must pass (lint + typecheck + tests).
203
+ 2. Use a Conventional Commit message (`feat:`, `fix:`, `docs:`, …).
204
+ 3. New ADF node types need a fixture in
205
+ `tests/roundtrip/test_node_coverage.py`.
206
+
207
+ ## License
208
+
209
+ MIT
adflux-0.1.0/README.md ADDED
@@ -0,0 +1,164 @@
1
+ # adflux
2
+
3
+ [![CI](https://github.com/mikejhill/adflux/actions/workflows/ci.yml/badge.svg)](https://github.com/mikejhill/adflux/actions/workflows/ci.yml)
4
+ [![Release](https://github.com/mikejhill/adflux/actions/workflows/release.yml/badge.svg)](https://github.com/mikejhill/adflux/actions/workflows/release.yml)
5
+ [![PyPI](https://img.shields.io/pypi/v/adflux.svg)](https://pypi.org/project/adflux/)
6
+ [![Python](https://img.shields.io/pypi/pyversions/adflux.svg)](https://pypi.org/project/adflux/)
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
+
9
+ A pure-Python converter between Markdown (CommonMark + GFM) and Atlassian
10
+ Document Format (ADF) — the JSON document model used by Confluence and
11
+ Jira. Round-trips losslessly, including ADF-only constructs like panels,
12
+ status badges, mentions, task lists, expand sections, and macros.
13
+
14
+ ```mermaid
15
+ flowchart LR
16
+ MD[Markdown] -->|markdown-it-py| IR((Internal IR + adf-* envelopes))
17
+ ADF[ADF JSON] -->|mapping.yaml| IR
18
+ IR -->|profile filter| W{writer}
19
+ W -->|CommonMark serializer| MD2[Markdown]
20
+ W -->|mapping.yaml| ADF2[ADF JSON]
21
+ ```
22
+
23
+ ## Why adflux
24
+
25
+ ADF is JSON, but no mature pure-Python tool converts it to and from
26
+ Markdown without losing information. `adflux` fills that gap:
27
+
28
+ - **No system dependencies.** `pip install adflux` — no Pandoc binary,
29
+ no Node, no Ruby.
30
+ - **Lossless ADF round-trips.** A declarative `mapping.yaml` plus a small
31
+ envelope convention round-trips every ADF construct, including ones
32
+ the library has never seen.
33
+ - **Idiomatic Markdown output.** Panels become GitHub alert blockquotes,
34
+ expand sections become `<details>`, smart cards become autolinks. The
35
+ output looks correct in GitHub, VS Code, and any standard viewer.
36
+ - **Fidelity profiles** make lossy / lossless behavior explicit and
37
+ selectable per call.
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ pip install adflux
43
+ ```
44
+
45
+ Requires Python ≥ 3.11. Linux, macOS, and Windows are CI-tested.
46
+
47
+ ## Quick start
48
+
49
+ ```python
50
+ from adflux import convert
51
+
52
+ # Markdown → ADF JSON
53
+ adf = convert(open("README.md").read(), src="md", dst="adf")
54
+
55
+ # ADF JSON → Markdown, dropping ADF-only constructs to plain content
56
+ md = convert(adf, src="adf", dst="md", profile="pretty-md")
57
+ ```
58
+
59
+ ```bash
60
+ adflux convert --from md --to adf README.md > readme.adf.json
61
+ adflux convert --from adf --to md page.json
62
+ adflux validate page.adf.json
63
+ ```
64
+
65
+ Full API and CLI reference: [`docs/usage.md`](docs/usage.md).
66
+
67
+ ## Fidelity profiles
68
+
69
+ | Profile | Behavior on lossy targets |
70
+ | ------------ | --------------------------------------------------------------- |
71
+ | `strict-adf` | Preserve every ADF construct (default). Round-trips losslessly. |
72
+ | `pretty-md` | Drop ADF-only envelopes silently; keep their visible content. |
73
+ | `fail-loud` | Raise `UnrepresentableNodeError` on the first envelope. |
74
+
75
+ Worked examples: [`docs/profiles.md`](docs/profiles.md).
76
+
77
+ ## Markdown rendering of ADF constructs
78
+
79
+ | ADF construct | Rendered as |
80
+ | ---------------------------------------- | ---------------------------------------------------- |
81
+ | `panel` (info/note/warning/…) | GitHub alert blockquote (`> [!NOTE]`, `> [!TIP]`, …) |
82
+ | `expand` | `<details><summary>title</summary>…</details>` |
83
+ | `inlineCard` / `blockCard` / `embedCard` | Autolink (`<https://…>`) |
84
+ | `taskList` / `taskItem` | GFM task list (`- [ ]`, `- [x]`) |
85
+ | `emoji`, `mention` | Plain text (`🚀`, `@alice`) |
86
+ | Everything else | HTML-comment marker (`<!--adf:status …-->`) |
87
+
88
+ The reader recognises every form on its way back, so `MD → ADF → MD` is
89
+ stable.
90
+
91
+ ## How it works
92
+
93
+ - **IR**: an in-memory document tree built on
94
+ [panflute](https://github.com/sergiocorreia/panflute) AST classes
95
+ (used purely as Python data structures — no Pandoc binary involved),
96
+ with `Div` / `Span` envelopes for ADF-only constructs.
97
+ - **Envelopes**: class prefix `adf-<nodeType>` plus a base64-JSON blob
98
+ for complex attributes. A universal `adf-raw` fallback guarantees zero
99
+ data loss.
100
+ - **Mapping**: every ADF node type is described in
101
+ [`src/adflux/formats/adf/mapping.yaml`](src/adflux/formats/adf/mapping.yaml).
102
+ Adding a new node type is a YAML edit.
103
+
104
+ Deeper dives:
105
+ [`docs/design.md`](docs/design.md) ·
106
+ [`docs/architecture.md`](docs/architecture.md) ·
107
+ [`docs/profiles.md`](docs/profiles.md) ·
108
+ [`docs/fidelity-matrix.md`](docs/fidelity-matrix.md) ·
109
+ [`docs/extending.md`](docs/extending.md) ·
110
+ [`docs/e2e-testing.md`](docs/e2e-testing.md).
111
+
112
+ ## Examples
113
+
114
+ Runnable scripts in [`examples/`](examples):
115
+
116
+ ```bash
117
+ python examples/md_to_adf.py README.md
118
+ python examples/adf_to_markdown.py
119
+ python examples/confluence_roundtrip.py
120
+ ```
121
+
122
+ ## Development
123
+
124
+ ```bash
125
+ git clone https://github.com/mikejhill/adflux
126
+ cd adflux
127
+ uv sync --all-groups
128
+ uv run poe check
129
+ ```
130
+
131
+ Common tasks via [poethepoet](https://poethepoet.natn.io/):
132
+
133
+ ```bash
134
+ poe test # unit + integration + round-trip + property tests
135
+ poe test-e2e # live Confluence + Jira round-trip suite (requires .env)
136
+ poe lint # ruff format --check + ruff check
137
+ poe typecheck # ty check src
138
+ poe cov # pytest with coverage report
139
+ poe check # lint + typecheck + test (run before opening a PR)
140
+ poe build # sdist + wheel into ./dist
141
+ ```
142
+
143
+ CI runs the full matrix on Linux, macOS, and Windows for Python 3.11–3.13.
144
+
145
+ ## Releasing
146
+
147
+ Releases are automated. Land changes on `main` using
148
+ [Conventional Commits](https://www.conventionalcommits.org/), then run
149
+ the **Release** workflow from the GitHub Actions tab. `go-semantic-release`
150
+ computes the next version, builds the sdist + wheel, creates a tagged
151
+ GitHub Release, and publishes to PyPI via OIDC trusted publishing.
152
+
153
+ ## Contributing
154
+
155
+ Issues and pull requests are welcome. Before opening a PR:
156
+
157
+ 1. `poe check` must pass (lint + typecheck + tests).
158
+ 2. Use a Conventional Commit message (`feat:`, `fix:`, `docs:`, …).
159
+ 3. New ADF node types need a fixture in
160
+ `tests/roundtrip/test_node_coverage.py`.
161
+
162
+ ## License
163
+
164
+ MIT