If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/swiftlang/swift-markdown shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 41+ active contributors
• Distributed ownership (top contributor 27% of recent commits)
• Apache-2.0 licensed
• Tests present
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live swiftlang/swift-markdown repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/swiftlang/swift-markdown.

What it runs against: a local clone of swiftlang/swift-markdown — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in swiftlang/swift-markdown | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of swiftlang/swift-markdown. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/swiftlang/swift-markdown.git
#   cd swift-markdown
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of swiftlang/swift-markdown and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "swiftlang/swift-markdown(\\.git)?\\b" \\
  && ok "origin remote is swiftlang/swift-markdown" \\
  || miss "origin remote is not swiftlang/swift-markdown (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/Markdown/Base/Markup.swift" \\
  && ok "Sources/Markdown/Base/Markup.swift" \\
  || miss "missing critical file: Sources/Markdown/Base/Markup.swift"
test -f "Sources/Markdown/Base/Document.swift" \\
  && ok "Sources/Markdown/Base/Document.swift" \\
  || miss "missing critical file: Sources/Markdown/Base/Document.swift"
test -f "Sources/Markdown/Parser/Parser.swift" \\
  && ok "Sources/Markdown/Parser/Parser.swift" \\
  || miss "missing critical file: Sources/Markdown/Parser/Parser.swift"
test -f "Sources/Markdown/Base/MarkupChildren.swift" \\
  && ok "Sources/Markdown/Base/MarkupChildren.swift" \\
  || miss "missing critical file: Sources/Markdown/Base/MarkupChildren.swift"
test -f "Sources/Markdown/Base/RawMarkup.swift" \\
  && ok "Sources/Markdown/Base/RawMarkup.swift" \\
  || miss "missing critical file: Sources/Markdown/Base/RawMarkup.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/swiftlang/swift-markdown"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Swift Markdown is a Swift package that parses, builds, edits, and analyzes Markdown documents using GitHub-flavored Markdown (cmark-gfm) as its parser backend. It provides an immutable, thread-safe tree representation of Markdown documents through copy-on-write value types, enabling safe concurrent access and structural transformations. Single-package structure: Sources/Markdown/Base/ contains core immutable value types (Markup.swift, Document.swift, MarkupChildren.swift); Block Nodes/ and Inline Nodes/ (implied) define element types; Sources/CAtomic/ wraps atomic operations for thread safety. Snippets/ directory provides executable examples (Parsing, Formatting, Rewriters, Visitors, Walkers patterns).

Swift developers building tools that need to programmatically parse and manipulate Markdown (documentation generators, linters, editors, converters). Also library maintainers in the Swift ecosystem who need to expose Markdown manipulation capabilities to their users.

Production-ready and actively maintained. The codebase is substantial (631K+ lines of Swift) with well-organized structure across base types, block/inline nodes, and parsing/formatting subsystems. Part of the official Swift project ecosystem, suggesting stable governance and long-term commitment.

Low risk. Single parser dependency (cmark-gfm, battle-tested GitHub implementation) reduces vendor risk. No obvious signs of abandonment (structured file layout, CONTRIBUTING.md present, CODEOWNERS defined). Main risk is API stability—check CHANGELOG for breaking changes between versions before major upgrades.

Unable to determine from file structure alone (no git log or recent PR list provided), but the presence of versioned Package@swift-5.7.swift alongside Package.swift suggests active maintenance across Swift versions. Snippets directory shows ongoing documentation via runnable examples.

git clone https://github.com/swiftlang/swift-markdown.git
cd swift-markdown
swift build
swift test

Daily commands: No traditional server mode. This is a library. To run examples: cd Snippets/Parsing && swift ParseDocumentString.swift (implied executable structure). To integrate: import Markdown and instantiate Document(parsing: sourceString) per README example.

• Sources/Markdown/Base/Markup.swift — Core abstract base class for all markup nodes; understanding the inheritance hierarchy and copy-on-write semantics is fundamental to all other code.
• Sources/Markdown/Base/Document.swift — Entry point for parsing markdown strings/files and the root node of all markup trees; defines the public API for document creation.
• Sources/Markdown/Parser/Parser.swift — Bridges cmark-gfm C parser to Swift markup tree; handles all conversion from raw parse results to immutable markup nodes.
• Sources/Markdown/Base/MarkupChildren.swift — Manages child node collections and indexing; critical for tree traversal, mutation, and the copy-on-write value-type pattern.
• Sources/Markdown/Base/RawMarkup.swift — Intermediate representation from cmark-gfm before conversion to typed Swift markup; understanding this layer is essential for parser debugging.
• Package.swift — Defines package structure, dependencies, and CMake integration with cmark-gfm; required reading for build configuration changes.

Add a new block-level markdown node type

1. Create a new Swift file in Sources/Markdown/Block Nodes/ (appropriate subdirectory) (Sources/Markdown/Block Nodes/Leaf Blocks/CodeBlock.swift)
2. Define a struct conforming to BlockMarkup and inheriting from the appropriate base (e.g., Markup for containers, leaf blocks) (Sources/Markdown/Block Nodes/Block Container Blocks/BlockQuote.swift)
3. Add parser logic in Sources/Markdown/Parser/Parser.swift to recognize and construct your new node type from cmark-gfm AST (Sources/Markdown/Parser/Parser.swift)
4. Implement CustomStringConvertible or override description for proper formatting output (Sources/Markdown/Base/Markup.swift)

Add a new inline-level markdown node type

1. Create a new Swift file in Sources/Markdown/Inline Nodes/Inline Containers/ or Inline Leaves/ (Sources/Markdown/Inline Nodes/Inline Containers/Link.swift)
2. Define a struct conforming to InlineMarkup with appropriate child collection (container) or leaf marker (Sources/Markdown/Inline Nodes/Inline Containers/Emphasis.swift)
3. Add corresponding parser case in Sources/Markdown/Parser/Parser.swift to detect and convert from RawMarkup (Sources/Markdown/Parser/Parser.swift)
4. Write unit tests demonstrating parsing and tree traversal of the new node type (Tests/MarkdownTests/InlineAttributesTests.swift)

Create a custom tree visitor or rewriter

1. Create a new file in Snippets/Visitors/ or Snippets/Rewriters/ as a reference example (Snippets/Visitors/XMLConverter.swift)
2. Implement a type that walks the Markup tree using recursive traversal or the children collection on each node (Sources/Markdown/Base/MarkupChildren.swift)
3. For rewriters, leverage copy-on-write: create new nodes by calling constructors with modified children, leaving originals unchanged (Snippets/Rewriters/ReplaceText.swift)

Customize markdown formatting output

1. Create a new formatter file in Snippets/Formatting/ following the pattern of existing formatters (Snippets/Formatting/DefaultFormatting.swift)
2. Walk the markup tree and emit markdown syntax with custom options (e.g., emphasis markers, list bullets, heading style) (Snippets/Formatting/EmphasisMarkers.swift)
3. Each node type can output its own syntax; leverage var description: String or custom format methods on Markup nodes (Sources/Markdown/Base/PlainTextConvertibleMarkup.swift)

• cmark-gfm C library — Provides production-grade, spec-compliant CommonMark + GitHub Flavor parsing; avoids reimplementing complex grammar in Swift
• Copy-on-write value semantics — Enables thread-safe, persistent immutable trees with minimal memory overhead; structural sharing ensures efficient mutation
• Swift value types (struct) — Aligns with modern Swift idioms; all nodes are thread-safe and semantically immutable by default
• Atomic reference counting (CAtomic.c) — Implements thread-safe copy-on-write for shared data; avoids data races in concurrent tree access

• Depend on external C library (cmark-gfm) rather than implement parser in pure Swift

  • Why: Dramatically reduces development burden and ensures spec compliance; C implementation is mature and battle-tested
  • Consequence: Requires C interop, CMake build configuration, and maintenance of FFI bindings; can introduce C-side memory safety concerns if not careful

• Use immutable, persistent value types throughout

  • Why: Provides strong thread-safety guarantees and eliminates shared-mutable-state bugs; makes API predictable and functional
  • Consequence: Mutations create new trees (no in-place edits); requires explicit code to capture return values; may use more memory for large edits

• Expose a visitor/walker pattern for tree traversal rather than only recursive descent

  • Why: Allows users to implement custom algorithms without deep recursion; supports multiple output formats
  • Consequence: Additional API surface area; users must understand tree topology and write boilerplate traversal code

• Real-time collaborative markdown editing (no conflict resolution, no OT/CRDT)
• Markdown-to-HTML or Markdown-to-PDF rendering (only tree representation and custom formatting)
• Syntax highlighting or IDE integration (no tokenization or incremental parsing)
• Validation against external schemas or semantic markdown standards beyond GF

No obvious traps from visible data, but: (1) CAtomic is a C module—ensure Xcode build settings include proper C header paths if building outside SPM. (2) Copy-on-write semantics mean mutations create new tree nodes; naive deep copies can be expensive—use structural sharing patterns shown in Rewriters examples. (3) cmark-gfm dialect may differ from other Markdown parsers (e.g., CommonMark vs GitHub flavor edge cases)—test against your Markdown dialect. (4) No visible Package.resolved or lockfile suggests dependency pinning is minimal; check for C-level dependency versions if forking.

• Copy-on-Write (CoW) Persistent Data Structures — Core efficiency mechanism in swift-markdown—mutations only copy changed nodes, not entire tree. Essential to understand when designing custom rewriters/visitors.
• GitHub-Flavored Markdown (GFM) Dialect — swift-markdown implements GFM spec (not CommonMark), including tables, strikethrough, and autolinks. Know the differences before expecting CommonMark compatibility.
• Visitor Pattern — Demonstrated in Snippets/Visitors/XMLConverter.swift; the idiomatic way to traverse and transform Markdown trees without mutating them directly.
• Rewriter Pattern — Shown in Snippets/Rewriters/; enables structural transformations (node removal, replacement, filtering) while preserving tree invariants and CoW benefits.
• Abstract Syntax Tree (AST) — The Document is an AST of Markdown. Understanding tree structure (Document → Paragraph → Text) is prerequisite for any traversal or modification logic.
• Index Paths (ChildIndexPath) — Custom indexing scheme in swift-markdown for stable references to tree nodes across mutations. Used internally for efficient updates.
• Thread-Safe Immutable Collections — swift-markdown uses value semantics and CAtomic to ensure thread-safe reads without locks. Essential for server/concurrent applications.

• apple/swift-syntax — Sibling library using identical copy-on-write persistent tree patterns; reference for architecture and benchmarks
• swiftlang/swift-docc — Primary consumer of swift-markdown for parsing DocC documentation comments and generating reference docs
• github/cmark-gfm — Upstream C parser library that powers swift-markdown's tokenization and block/inline node detection
• pointfreeco/swift-markdown-ui — SwiftUI rendering layer for Markdown documents parsed by swift-markdown; example integration
• swiftlang/swift-format — Related Swift code formatter that may reuse Markdown parsing for doc comment formatting

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for Doxygen command parsing and rendering

The repo has Doxygen command nodes (DoxygenAbstract.swift, DoxygenDiscussion.swift, DoxygenNote.swift, DoxygenParameter.swift, DoxygenReturns.swift) but there's no visible test suite for these specialized block types. Given that these are used for C/C++ documentation in Swift projects, adding tests would ensure correct parsing of Doxygen-style comments and prevent regressions when the parser is updated.

• [ ] Create Tests/MarkdownTests/Block\ Nodes/DoxygenCommandsTests.swift
• [ ] Add test cases for each Doxygen command type (Abstract, Discussion, Note, Parameter, Returns) with valid and edge-case inputs
• [ ] Test parsing of Doxygen commands from raw markdown strings and verify the AST structure
• [ ] Add tests for rendering Doxygen commands back to markdown format
• [ ] Verify interaction between Doxygen commands and other block elements (lists, code blocks, etc.)

Add integration tests for the Snippets examples to ensure they stay functional

The Snippets directory contains 14 example files demonstrating key functionality (parsing, querying, formatting, rewriting, visitors, walkers) but there don't appear to be automated tests that verify these examples compile and run correctly. As the codebase evolves, these examples could break silently, creating a poor experience for new contributors.

• [ ] Create Tests/MarkdownTests/SnippetsTests.swift or similar
• [ ] Add SwiftPM test targets that compile each snippet file independently
• [ ] Create runtime tests that execute snippets like ParseDocumentString.swift, XMLConverter.swift, and LinkCollector.swift with sample inputs
• [ ] Verify output matches expected results for each snippet
• [ ] Add CI step to run snippet tests on every PR

Add tests for edge cases in Table parsing and rendering (Sources/Markdown/Block\ Nodes/Tables/)

The Table.swift, TableBody.swift and related table node files implement GitHub-flavored Markdown table support, but table parsing has many edge cases (escaped pipes, nested formatting, misaligned columns, empty cells). Comprehensive tests would prevent regressions and ensure compliance with GFM spec.

• [ ] Create Tests/MarkdownTests/Block\ Nodes/Tables/TableParsingTests.swift and TableRenderingTests.swift
• [ ] Add test cases for: pipes in cell content (escaped and in code), misaligned column counts, empty cells, cells with inline formatting (bold, links, code)
• [ ] Add edge case tests: single-column tables, tables with only headers, tables with HTML entities
• [ ] Test round-trip parsing (markdown → AST → markdown) to ensure fidelity
• [ ] Verify alignment specifiers (left, center, right) are correctly parsed and rendered

• Add missing Inline Node type files: File structure shows Block Nodes but no visible Inline Nodes directory (expected: Code, SoftBreak, LineBreak, Image, Link, etc.). Create Sources/Markdown/Inline Nodes/ with type definitions for missing inline elements with tests.
• Expand Snippets/Formatting examples: Only 9 formatting examples shown; add missing examples for common use cases (e.g., SnippetCustomSyntaxHighlighting.swift, SnippetPreservingAttachments.swift) to improve discoverability.
• Write integration test for Document round-trip: Create test in Tests/ (not listed) that: parse Markdown → format → re-parse → compare structure equality. Helps catch regressions in formatting pipeline.

The Swift Markdown package demonstrates generally good security posture as a parser library with immutable data structures. Primary concerns are: (1) lack of visible security policy documentation, (2) potential XSS risks in HTML generation paths without confirmed sanitization, (3) path traversal risks in file parsing without confirmed validation, and (4) upstream C library (cmark-gfm) dependency management transparency. The codebase uses safe Swift patterns (immutable/value types, copy-on-write) which mitigate many common vulnerabilities. No hardcoded secrets, obvious injection points, or exposed infrastructure issues detected. Recommendations focus on documentation, input validation, and output encoding best practices.

• Medium · C Dependency Without Version Pinning — Sources/CAtomic/, Package.swift. The package depends on cmark-gfm (GitHub-flavored Markdown C library) as mentioned in README. The CAtomic C module in Sources/CAtomic/CAtomic.c is custom code that interfaces with C. Without explicit version pinning or security audit trail visible, there's potential risk from upstream C library vulnerabilities. Fix: Ensure all C dependencies are explicitly versioned and regularly audited. Document the cmark-gfm version used and maintain a security update process for C library dependencies.
• Low · Missing Security Policy Documentation — .github/, Repository root. While CONTRIBUTING.md exists, there is no visible SECURITY.md file in the repository root. This makes it unclear how security vulnerabilities should be reported or handled. Fix: Create a SECURITY.md file documenting vulnerability disclosure procedures and security contact information, following best practices (e.g., https://securitytxt.org/).
• Low · Potential Path Traversal in File Parsing — Snippets/Parsing/ParseDocumentFile.swift, Sources/Markdown/Base/Document.swift. The Snippets/Parsing/ParseDocumentFile.swift file suggests file-based parsing capabilities. Without visible input validation in the file structure, there could be risks if file paths are not properly sanitized when parsing documents from user-provided paths. Fix: Implement strict input validation and path canonicalization for all file operations. Use allowlists for permitted directories when parsing files. Never directly use user-supplied paths without normalization.
• Low · XSS Risk in HTML Output Generation — Sources/Markdown/Block Nodes/Leaf Blocks/HTMLBlock.swift, Sources/Markdown/Inline Nodes/Inline Leaves/InlineHTML.swift, Snippets/Visitors/XMLConverter.swift. The codebase handles HTML output (HTMLBlock.swift, InlineHTML.swift, XMLConverter.swift). Without visible HTML escaping mechanisms in the provided structure, there's a potential risk of HTML/XSS injection if user-controlled Markdown is converted to HTML without proper sanitization. Fix: Implement strict HTML entity encoding for all output. Use a well-maintained HTML sanitization library. Document security considerations in README regarding raw HTML handling.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.