mrsf — Markdown Review Sidecar Format (Python)

Python CLI and SDK for the MRSF (Sidemark) specification. A 1:1 port of the Node.js @mrsf/cli package.

Installation

pip install mrsf

CLI Usage

# Validate sidecar files
mrsf validate docs/*.review.yaml
mrsf validate --strict README.md

# Add a comment
mrsf add README.md --text "Fix this" --line 10

# Re-anchor after edits
mrsf reanchor docs/
mrsf reanchor --staged --force
mrsf reanchor --dry-run --threshold 0.8

# List comments
mrsf list docs/
mrsf list --open --severity high --json

# Resolve/unresolve
mrsf resolve doc.md.review.yaml abc123
mrsf resolve doc.md.review.yaml abc123 --undo

# Check anchor health
mrsf status docs/
mrsf status --json

# Create empty sidecar
mrsf init README.md

# Rename document + sidecar
mrsf rename old.md new.md

# Watch for changes
mrsf watch docs/ --reanchor --force

mrsf add uses user.name from the repository-local .git/config when --author is omitted. Pass --author to override it; global Git identity is not used.

Global Options

SDK Usage

import mrsf

# Parse a sidecar file
doc = mrsf.parse_sidecar("README.md.review.yaml")

# Iterate comments
for comment in doc.comments:
    print(f"{comment.author}: {comment.text} (line {comment.line})")

# Add a comment
opts = mrsf.AddCommentOptions(
    author="Alice",
    text="Consider rephrasing this section",
    line=42,
    selected_text="The quick brown fox",
    type="suggestion",
    severity="medium",
)
new_comment = mrsf.add_comment(doc, opts)

# Add a comment with tool-specific x_* metadata
bot_opts = mrsf.AddCommentOptions(
    author="review-bot",
    text="Needs a second pass",
    line=12,
    extensions={
        "x_source": "review-bot",
        "x_score": 0.91,
        "x_labels": ["needs-review", "docs"],
    },
)
mrsf.add_comment(doc, bot_opts)

# Write back (preserves YAML formatting)
mrsf.write_sidecar("README.md.review.yaml", doc)

# Validate
result = mrsf.validate(doc)
if not result.valid:
    for err in result.errors:
        print(f"Error: {err.message}")

# Re-anchor after edits
results = mrsf.reanchor_document(doc, document_lines)
for r in results:
    print(f"{r.comment_id}: {r.status} ({r.reason})")

# Discover sidecar for a document
sidecar_path = mrsf.discover_sidecar("docs/guide.md")

# Fuzzy text matching
score = mrsf.combined_score("original text", "edited text")
matches = mrsf.fuzzy_search("search text", ["line 1", "line 2", "line 3"])

API Reference

Parsing

Writing

Comments

AddCommentOptions accepts an optional extensions map. Keys must start with x_, and entries are written back to the sidecar as flat x_* fields on the comment.

Validation

Re-anchoring

The Python implementation uses the same revision projection, bounded candidate retrieval, Markdown structure, global reconciliation, and confidence calibration as the TypeScript implementation. Browser integrations can use the same pure building blocks when they retain a source document snapshot. See the non-normative implementation guide for the complete pipeline and runtime boundaries.

Discovery

Fuzzy Matching

Git Integration

Data Types

@dataclass
class MrsfDocument:
    mrsf_version: str
    document: str
    comments: list[Comment]

@dataclass
class Comment:
    id: str
    author: str
    timestamp: str
    text: str
    resolved: bool = False
    line: int | None = None
    end_line: int | None = None
    selected_text: str | None = None
    selected_text_hash: str | None = None
    type: str | None = None
    severity: str | None = None  # "low" | "medium" | "high"
    reply_to: str | None = None
    commit: str | None = None
    # ... plus start_column, end_column, anchored_text

Requirements

• Python ≥ 3.10
• Dependencies: click, jsonschema, ruamel.yaml, rapidfuzz, rich, watchdog

Development

cd python
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest -v

# Lint
ruff check src/ tests/

# Type check
mypy src/mrsf/

License

MIT — see LICENSE.