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.
- adflux-0.1.0/.gitignore +267 -0
- adflux-0.1.0/CHANGELOG.md +27 -0
- adflux-0.1.0/LICENSE +21 -0
- adflux-0.1.0/PKG-INFO +209 -0
- adflux-0.1.0/README.md +164 -0
- adflux-0.1.0/docs/architecture.md +74 -0
- adflux-0.1.0/docs/design.md +179 -0
- adflux-0.1.0/docs/e2e-testing.md +116 -0
- adflux-0.1.0/docs/extending.md +62 -0
- adflux-0.1.0/docs/fidelity-matrix.md +58 -0
- adflux-0.1.0/docs/profiles.md +75 -0
- adflux-0.1.0/docs/usage.md +116 -0
- adflux-0.1.0/examples/README.md +24 -0
- adflux-0.1.0/examples/adf_to_markdown.py +35 -0
- adflux-0.1.0/examples/confluence_roundtrip.py +43 -0
- adflux-0.1.0/examples/extensions.md +26 -0
- adflux-0.1.0/examples/md_to_adf.py +29 -0
- adflux-0.1.0/examples/sample.adf.json +88 -0
- adflux-0.1.0/pyproject.toml +204 -0
- adflux-0.1.0/src/adflux/__init__.py +25 -0
- adflux-0.1.0/src/adflux/api.py +82 -0
- adflux-0.1.0/src/adflux/cli.py +129 -0
- adflux-0.1.0/src/adflux/errors.py +55 -0
- adflux-0.1.0/src/adflux/formats/__init__.py +74 -0
- adflux-0.1.0/src/adflux/formats/adf/__init__.py +15 -0
- adflux-0.1.0/src/adflux/formats/adf/mapping.py +137 -0
- adflux-0.1.0/src/adflux/formats/adf/mapping.yaml +233 -0
- adflux-0.1.0/src/adflux/formats/adf/reader.py +268 -0
- adflux-0.1.0/src/adflux/formats/adf/schema/adf-minimal.schema.json +45 -0
- adflux-0.1.0/src/adflux/formats/adf/schema.py +77 -0
- adflux-0.1.0/src/adflux/formats/adf/writer.py +325 -0
- adflux-0.1.0/src/adflux/formats/markdown/__init__.py +59 -0
- adflux-0.1.0/src/adflux/formats/markdown/pretty.py +757 -0
- adflux-0.1.0/src/adflux/formats/markdown/reader.py +352 -0
- adflux-0.1.0/src/adflux/formats/markdown/writer.py +333 -0
- adflux-0.1.0/src/adflux/ir/__init__.py +27 -0
- adflux-0.1.0/src/adflux/ir/envelope.py +177 -0
- adflux-0.1.0/src/adflux/ir/profile_filter.py +54 -0
- adflux-0.1.0/src/adflux/logging.py +54 -0
- adflux-0.1.0/src/adflux/profiles.py +82 -0
- adflux-0.1.0/tests/conftest.py +13 -0
- adflux-0.1.0/tests/e2e/__init__.py +15 -0
- adflux-0.1.0/tests/e2e/compare.py +126 -0
- adflux-0.1.0/tests/e2e/confluence_client.py +144 -0
- adflux-0.1.0/tests/e2e/conftest.py +224 -0
- adflux-0.1.0/tests/e2e/jira_client.py +135 -0
- adflux-0.1.0/tests/e2e/test_confluence_roundtrip.py +315 -0
- adflux-0.1.0/tests/e2e/test_jira_roundtrip.py +111 -0
- adflux-0.1.0/tests/integration/__init__.py +0 -0
- adflux-0.1.0/tests/integration/test_end_to_end.py +61 -0
- adflux-0.1.0/tests/roundtrip/__init__.py +0 -0
- adflux-0.1.0/tests/roundtrip/test_adf_property.py +63 -0
- adflux-0.1.0/tests/roundtrip/test_adf_roundtrip.py +95 -0
- adflux-0.1.0/tests/roundtrip/test_node_coverage.py +225 -0
- adflux-0.1.0/tests/roundtrip/test_table_roundtrip.py +69 -0
- adflux-0.1.0/tests/unit/__init__.py +0 -0
- adflux-0.1.0/tests/unit/test_adf_reader.py +180 -0
- adflux-0.1.0/tests/unit/test_adf_schema.py +53 -0
- adflux-0.1.0/tests/unit/test_adf_writer.py +89 -0
- adflux-0.1.0/tests/unit/test_envelope.py +101 -0
- adflux-0.1.0/tests/unit/test_mapping_loader.py +62 -0
- adflux-0.1.0/tests/unit/test_profile_filter.py +86 -0
- adflux-0.1.0/tests/unit/test_profiles.py +48 -0
adflux-0.1.0/.gitignore
ADDED
|
@@ -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
|
+
[](https://github.com/mikejhill/adflux/actions/workflows/ci.yml)
|
|
49
|
+
[](https://github.com/mikejhill/adflux/actions/workflows/release.yml)
|
|
50
|
+
[](https://pypi.org/project/adflux/)
|
|
51
|
+
[](https://pypi.org/project/adflux/)
|
|
52
|
+
[](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
|
+
[](https://github.com/mikejhill/adflux/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/mikejhill/adflux/actions/workflows/release.yml)
|
|
5
|
+
[](https://pypi.org/project/adflux/)
|
|
6
|
+
[](https://pypi.org/project/adflux/)
|
|
7
|
+
[](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
|