ARCHITECTURE: CommonMark Parser
| Field | Value |
|---|---|
| Version | 20260815 V1 |
| Description | Defines the executable boundary and standard-library architecture for the CommonMark parser. |
| Depends On | — |
| Provides | executable commonmark |
| Consumes | — |
Intent
The application is a command-line CommonMark 0.31.2 parser. The executable commonmark reads UTF-8 Markdown from standard input and writes rendered HTML to standard output.
Boundaries
| Module | Responsibility |
|---|---|
commonmark | Executable process boundary, UTF-8 stream handling, and exit status. |
| Parser implementation | Block parsing, link-reference collection, inline parsing, and HTML rendering. |
sources/ | Supplied immutable conformance assets used only by verification. |
Block structure is resolved before inline structure. Link-reference definitions collected during block parsing are available to inline parsing.
Technology Stack
- Python 3 for the executable and parser.
- Python standard library only at runtime.
- POSIX shell for the supplied conformance harness.
Technical Decisions
- Do not use a public Markdown implementation or third-party runtime dependency.
- Preserve the executable name and standard-input/standard-output contract.
- Replace U+0000 with U+FFFD according to the CommonMark specification.
- Keep supplied scoring assets unchanged.
Programmatic Acceptance
=== AC interface-executable ===
Intent: The application root contains an executable named commonmark.
import os
path = "commonmark" assert os.path.isfile(path) assert os.access(path, os.X_OK) === END AC interface-executable ===
=== AC interface-process ===
Intent: The executable accepts standard input and terminates successfully.
import subprocess
source = "interface probe\n" result = subprocess.run( ["./commonmark"], input=source, capture_output=True, text=True, ) print(result.stdout) print(result.stderr) assert result.returncode == 0 === END AC interface-process ===
=== AC interface-utf8 ===
Intent: The executable accepts UTF-8 input and terminates successfully.
import subprocess
source = "UTF-8 interface probe\n" result = subprocess.run( ["./commonmark"], input=source, capture_output=True, text=True, encoding="utf-8", ) print(result.stdout) print(result.stderr) assert result.returncode == 0 === END AC interface-utf8 ===
User Acceptance
- None.
Guardrails
- Do not modify supplied conformance assets.
- Do not add a public Markdown implementation as a dependency.