Complete async rewrite with bulk export, custom fields, and JQL support

[dchuk]

Summary

This PR represents a comprehensive evolution of jarkdown from a synchronous single-issue exporter into a fully async, feature-rich Jira archival tool. The work was completed across 4 development phases plus a final cleanup pass.

Highlights

• Full async rewrite — replaced requests with aiohttp for concurrent I/O
• Subcommand CLI — export, bulk, query, setup with backward compatibility
• Bulk export — concurrent multi-issue export with semaphore-based rate limiting
• JQL search — query Jira with JQL and export all matching issues
• Custom fields — configurable field rendering with Atlassian Document Format (ADF) parsing
• 25+ ADF node types — tables, panels, code blocks, media, task lists, decision items, etc.
• YAML frontmatter — machine-readable metadata in every exported markdown file
• Retry with backoff — exponential backoff + jitter for HTTP 429/503/504
• uv package manager — migrated from pip/setuptools to Hatchling + uv
• 231 tests across 13 test modules

---

Phase 1: Standard Field Coverage

Extended the markdown output with structured sections for fields that were previously ignored:

• YAML frontmatter with always-present schema (key, summary, status, type, priority, assignee, reporter, created, updated, resolved, labels, components, fix versions, affected versions, time tracking)
• Linked issues section with relationship types (blocks, is blocked by, duplicates, etc.)
• Subtasks section with status indicators
• Worklogs section with author, time spent, and ADF-to-plaintext comment conversion
• Environment section (HTML-to-markdown)
• Integration tests with comprehensive JSON fixtures

Phase 2: Custom Fields & ADF

Added a full pipeline for custom Jira fields and rich document parsing:

• ConfigManager — TOML-based config with ~/.config/jarkdown/config.toml
• FieldMetadataCache — XDG-compliant caching of Jira field metadata with 24h TTL
• CustomFieldRenderer — type-aware rendering (text, number, date, user, option, array, cascading select)
• ADF parser — 25+ Atlassian Document Format node types:
  • Block nodes: paragraph, heading, blockquote, code block, rule, media single/group
  • List nodes: bullet, ordered, task list, decision list
  • Complex nodes: table (with header detection), panel, expand
  • Inline nodes: text (with marks), mention, emoji, date, status, inline card, hard break
• Field filter — --fields, --exclude-fields, --include-all-fields CLI flags
• setup subcommand — interactive credential configuration wizard

Phase 3: uv Migration

Modernized the build and dependency toolchain:

• Hatchling build backend (replaced setuptools)
• uv lockfile for reproducible dependency resolution
• CI migration — all GitHub Actions jobs (test, lint, docs, publish) updated from pip to uv
• Updated contributing docs and developer setup instructions

Phase 4: Bulk Export & JQL

The largest phase — async rewrite and concurrent export engine:

• aiohttp client — JiraApiClient rewritten as async context manager with TCPConnector(limit_per_host=5)
• Retry module — RetryConfig dataclass, parse_retry_after(), exponential backoff with jitter
• bulk subcommand — accepts multiple issue keys, exports concurrently
• query subcommand — accepts JQL string, fetches matching issues via search_jql() with nextPageToken pagination
• BulkExporter — asyncio.Semaphore for configurable concurrency (default 3), asyncio.gather(return_exceptions=True) for partial failure handling
• Progress reporting — \rExporting {n}/{total}... ({key}) on stderr
• Index file — index.md with summary table of all exported issues (key, summary, status, type, assignee, result)
• Backward compatibility — bare jarkdown ISSUE-KEY still works (auto-injects export)

Cleanup Pass

• Removed unused requests dependency (legacy from pre-async era)
• Extracted export_core.py with shared perform_export() function, eliminating duplicated export logic between single-issue and bulk export paths

---

Architecture

CLI (jarkdown.py)
 ├── export → export_core.perform_export()
 ├── bulk   → BulkExporter.export_bulk() → [Semaphore] → export_core.perform_export()
 ├── query  → search_jql() → BulkExporter
 └── setup  → interactive config wizard

export_core.perform_export():
  JiraApiClient.fetch_issue()
  → AttachmentHandler.download_all_attachments()
  → FieldMetadataCache (optional)
  → CustomFieldRenderer (optional)
  → MarkdownConverter.compose_markdown()
  → write files

New Modules (10 total)

Module	Purpose
jarkdown.py	CLI orchestrator with subcommand dispatch
jira_api_client.py	Async aiohttp Jira REST API client
attachment_handler.py	Async attachment downloader
markdown_converter.py	HTML/ADF to Markdown with frontmatter
export_core.py	Shared single-issue export workflow
bulk_exporter.py	Concurrent multi-issue export engine
retry.py	Exponential backoff with jitter
config_manager.py	TOML config loading and merging
field_cache.py	XDG-compliant field metadata cache
custom_field_renderer.py	Type-aware custom field rendering
exceptions.py	Exception hierarchy (JarkdownError base)

Test Coverage

• 13 test modules, 231 tests, all passing
• JSON fixtures for realistic API response mocking
• Async test support via pytest-asyncio with asyncio_mode=auto
• Session-boundary mocking (aioresponses at aiohttp level)

Dependencies

Runtime (6): aiohttp, markdownify, python-dotenv, PyYAML, platformdirs, tomli
Dev: pytest, pytest-asyncio, pytest-mock, aioresponses, ruff

Test plan

• All 231 existing tests pass
• Merge conflicts with upstream resolved (our fork is the superset)
• Manual smoke test: jarkdown export <ISSUE-KEY>
• Manual smoke test: jarkdown bulk <KEY-1> <KEY-2>
• Manual smoke test: jarkdown query "project = TEST"

🤖 Generated with Claude Code

[dchuk]

Hey, this is a great project. I realize what I just created a pull request for is a substantial rewrite, sorry for the abrupt move here. It's overall working really well for me in my testing, so I wanted to put it here for your consideration, no pride of ai-authorship here.