dotmd-parser 0.6.2__tar.gz → 0.9.0__tar.gz

{dotmd_parser-0.6.2/src/dotmd_parser.egg-info → dotmd_parser-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotmd-parser
-Version: 0.6.2
+Version: 0.9.0
 Summary: Dependency graph parser, single-file folder index (dotmd-index.md), and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, generate RAG-friendly overviews, and ingest into OpenRAG
 Author: dotmd-projects
 License-Expression: MIT
@@ -167,6 +167,24 @@ print(result["placeholders"])  # Unresolved {{variable}} names
 print(result["warnings"])      # Circular refs, missing files, etc.
 ```
 
+#### Injection scanning
+
+`resolve` scans content pulled in via `@include` for prompt-injection
+patterns (role spoofing like `System:`, instruction overrides like "ignore
+previous instructions"). Findings print to stderr; the expanded content is
+unchanged by default.
+
+```bash
+dotmd-parser resolve ./skill/SKILL.md                      # scan on, warn (default)
+dotmd-parser resolve ./skill/SKILL.md --no-scan            # disable scanning
+dotmd-parser resolve ./skill/SKILL.md --scan-rule tool-exfil   # add an opt-in rule
+dotmd-parser resolve ./skill/SKILL.md --block              # replace injected includes with a placeholder
+```
+
+The root/entry file is trusted and not scanned — only `@include`-pulled
+files are. Matches inside fenced code blocks are ignored, and
+`<!-- dotmd-allow: role-spoof -->` (or `all`) in a file suppresses that rule.
+
 ### dependents_of — Reverse dependency query
 
 ```python
@@ -221,11 +239,12 @@ from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders,
 | `dotmd-parser dotmd-index <path> --push-openrag` | After writing, ingest into OpenRAG (`pip install dotmd-parser[openrag]`) |
 | `dotmd-parser index <path>` | Build and save `.claude/dotmd-index.json` |
 | `dotmd-parser index <path> --scope <subdir>` | Incrementally re-index one subfolder, merge into the existing index |
-| `dotmd-parser check <path>` | Exit non-zero on cycles / missing refs (CI-friendly) |
+| `dotmd-parser check <path>` | Health gate (CI): cycles, missing refs, unresolved placeholders, conflicts |
 | `dotmd-parser affects <path> <file>` | Reverse dependencies of `<file>` |
 | `dotmd-parser deps <path> <file>` | Direct dependencies of `<file>` |
 | `dotmd-parser digest <path>` | Token-efficient text summary for LLM context |
 | `dotmd-parser tree <path>` | ASCII dependency tree |
+| `dotmd-parser plan <path>` | Parallel delegation plan (JSON) |
 | `dotmd-parser resolve <file> [--var k=v]` | Recursively expand `@include` |
 | `dotmd-parser analyze <path>` | AI dependency detection (requires `ANTHROPIC_API_KEY`) |
 | `dotmd-parser analyze <path> --dry-run` | **API-free**: estimate tokens and USD cost |
@@ -243,6 +262,71 @@ dotmd-parser digest ./my-skill/            # compact summary for the LLM
 dotmd-parser affects ./my-skill/ shared/role.md
 ```
 
+### `ledger` / `risk` — edit-risk governance
+
+Record per-file risk history in an append-only JSONL ledger
+(`.claude/dotmd-ledger.jsonl`) and query it before editing. `risk` combines
+reverse-dependency impact (`affects`) with active risk tags (ledger replay ∪
+frontmatter `risk:`).
+
+```bash
+dotmd-parser ledger add . shared/role.md --tag fix-failed --note "retry hung"
+dotmd-parser ledger clear . shared/role.md --tag fix-failed   # or --all
+dotmd-parser risk . shared/role.md                            # text report
+dotmd-parser risk . shared/role.md --json
+```
+
+Tags: `fix-failed`, `fragile`, `security-sensitive`, `deprecated` (the first
+two are "high"). `--fail-on high|any|never` controls the exit code, so a
+PreToolUse hook can warn before risky edits:
+
+```bash
+dotmd-parser risk . "$FILE_PATH" --fail-on high \
+  || echo "[dotmd] high-risk file (last fix failed / security-sensitive) — review before editing"
+```
+
+### `check` — guidance health gate (CI)
+
+Deterministic health check over the dependency graph. Detects cycles and
+missing references (errors), plus unresolved `{{placeholders}}` and
+conflicting directives (warnings). Optionally flags orphan files.
+
+```bash
+dotmd-parser check ./my-skill                       # text, fails on errors
+dotmd-parser check ./my-skill --fail-on warning     # also fail on warnings
+dotmd-parser check ./my-skill --format json
+dotmd-parser check ./my-skill --format sarif --out dotmd.sarif
+dotmd-parser check ./my-skill --check orphans       # opt-in orphan detection
+```
+
+`--fail-on` chooses the exit-code threshold (`error` default, `warning`, or
+`never`). Use `--format sarif` with GitHub's `upload-sarif` action to get
+inline PR annotations:
+
+```yaml
+- run: dotmd-parser check . --format sarif --out dotmd.sarif --fail-on never
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: dotmd.sarif }
+- run: dotmd-parser check . --fail-on warning   # gate the PR
+```
+### `plan` — parallel delegation plan
+
+Generate a static execution plan from the `@delegate` graph: topological
+batches (parallel levels), per-task subtree context, plus conflict and cycle
+pre-detection. Intended for a parent agent that fans out subagents.
+
+```bash
+dotmd-parser plan ./my-skill            # plan(JSON) to stdout
+dotmd-parser plan ./my-skill --ascii    # human-readable view
+dotmd-parser plan ./my-skill --out plan.json
+dotmd-parser plan ./my-skill --strict   # exit 1 on cycles/conflicts (CI)
+```
+
+Each task in the JSON carries a `context` array (the subtree files to hand the
+subagent). Same-batch shared dependencies are reported in `conflicts[]` as
+warnings — the batch stays parallel. Mutual `@delegate` references are reported
+in `cycles[]` and excluded from batches.
+
 ## `dotmd-index.md` — folder overview in a single file
 
 `dotmd-parser dotmd-index <path>` writes `<path>/dotmd-index.md`, a
@@ -305,6 +389,28 @@ dotmd-parser dotmd-index ./docs/ --push-openrag
 **search index** (full-content semantic retrieval). Register OpenRAG's
 MCP server with Claude Code to use both surfaces from the same client.
 
+### Cache-affine order (`--order cache`)
+
+`dotmd-index --order cache` lists the `## Files` section with the
+least-frequently-changed files first (estimated from git history), so the
+generated `dotmd-index.md` keeps a stable prefix across regenerations — better
+KV-cache reuse for LLMs that read it. Default `--order alpha` is unchanged.
+
+```bash
+dotmd-parser dotmd-index ./skill --order cache
+dotmd-parser dotmd-index ./skill --order cache --stdout
+```
+
+Measure the effect with `stability` (compare two generations):
+
+```bash
+dotmd-parser stability old-index.md new-index.md          # prefix stable: 42/50 lines (0.84)
+dotmd-parser stability old-index.md new-index.md --json
+```
+
+Outside a git repo (or for untracked files) frequency is treated as 0, so
+`cache` degrades gracefully to alphabetical order.
+
 ## `analyze` — AI-assisted dependency detection
 
 Use when a folder of markdown has **no explicit directives yet**. `analyze`

{dotmd_parser-0.6.2 → dotmd_parser-0.9.0}/README.md

@@ -130,6 +130,24 @@ print(result["placeholders"])  # Unresolved {{variable}} names
 print(result["warnings"])      # Circular refs, missing files, etc.
 ```
 
+#### Injection scanning
+
+`resolve` scans content pulled in via `@include` for prompt-injection
+patterns (role spoofing like `System:`, instruction overrides like "ignore
+previous instructions"). Findings print to stderr; the expanded content is
+unchanged by default.
+
+```bash
+dotmd-parser resolve ./skill/SKILL.md                      # scan on, warn (default)
+dotmd-parser resolve ./skill/SKILL.md --no-scan            # disable scanning
+dotmd-parser resolve ./skill/SKILL.md --scan-rule tool-exfil   # add an opt-in rule
+dotmd-parser resolve ./skill/SKILL.md --block              # replace injected includes with a placeholder
+```
+
+The root/entry file is trusted and not scanned — only `@include`-pulled
+files are. Matches inside fenced code blocks are ignored, and
+`<!-- dotmd-allow: role-spoof -->` (or `all`) in a file suppresses that rule.
+
 ### dependents_of — Reverse dependency query
 
 ```python
@@ -184,11 +202,12 @@ from dotmd_parser import parse_directives, parse_read_refs, parse_placeholders,
 | `dotmd-parser dotmd-index <path> --push-openrag` | After writing, ingest into OpenRAG (`pip install dotmd-parser[openrag]`) |
 | `dotmd-parser index <path>` | Build and save `.claude/dotmd-index.json` |
 | `dotmd-parser index <path> --scope <subdir>` | Incrementally re-index one subfolder, merge into the existing index |
-| `dotmd-parser check <path>` | Exit non-zero on cycles / missing refs (CI-friendly) |
+| `dotmd-parser check <path>` | Health gate (CI): cycles, missing refs, unresolved placeholders, conflicts |
 | `dotmd-parser affects <path> <file>` | Reverse dependencies of `<file>` |
 | `dotmd-parser deps <path> <file>` | Direct dependencies of `<file>` |
 | `dotmd-parser digest <path>` | Token-efficient text summary for LLM context |
 | `dotmd-parser tree <path>` | ASCII dependency tree |
+| `dotmd-parser plan <path>` | Parallel delegation plan (JSON) |
 | `dotmd-parser resolve <file> [--var k=v]` | Recursively expand `@include` |
 | `dotmd-parser analyze <path>` | AI dependency detection (requires `ANTHROPIC_API_KEY`) |
 | `dotmd-parser analyze <path> --dry-run` | **API-free**: estimate tokens and USD cost |
@@ -206,6 +225,71 @@ dotmd-parser digest ./my-skill/            # compact summary for the LLM
 dotmd-parser affects ./my-skill/ shared/role.md
 ```
 
+### `ledger` / `risk` — edit-risk governance
+
+Record per-file risk history in an append-only JSONL ledger
+(`.claude/dotmd-ledger.jsonl`) and query it before editing. `risk` combines
+reverse-dependency impact (`affects`) with active risk tags (ledger replay ∪
+frontmatter `risk:`).
+
+```bash
+dotmd-parser ledger add . shared/role.md --tag fix-failed --note "retry hung"
+dotmd-parser ledger clear . shared/role.md --tag fix-failed   # or --all
+dotmd-parser risk . shared/role.md                            # text report
+dotmd-parser risk . shared/role.md --json
+```
+
+Tags: `fix-failed`, `fragile`, `security-sensitive`, `deprecated` (the first
+two are "high"). `--fail-on high|any|never` controls the exit code, so a
+PreToolUse hook can warn before risky edits:
+
+```bash
+dotmd-parser risk . "$FILE_PATH" --fail-on high \
+  || echo "[dotmd] high-risk file (last fix failed / security-sensitive) — review before editing"
+```
+
+### `check` — guidance health gate (CI)
+
+Deterministic health check over the dependency graph. Detects cycles and
+missing references (errors), plus unresolved `{{placeholders}}` and
+conflicting directives (warnings). Optionally flags orphan files.
+
+```bash
+dotmd-parser check ./my-skill                       # text, fails on errors
+dotmd-parser check ./my-skill --fail-on warning     # also fail on warnings
+dotmd-parser check ./my-skill --format json
+dotmd-parser check ./my-skill --format sarif --out dotmd.sarif
+dotmd-parser check ./my-skill --check orphans       # opt-in orphan detection
+```
+
+`--fail-on` chooses the exit-code threshold (`error` default, `warning`, or
+`never`). Use `--format sarif` with GitHub's `upload-sarif` action to get
+inline PR annotations:
+
+```yaml
+- run: dotmd-parser check . --format sarif --out dotmd.sarif --fail-on never
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: dotmd.sarif }
+- run: dotmd-parser check . --fail-on warning   # gate the PR
+```
+### `plan` — parallel delegation plan
+
+Generate a static execution plan from the `@delegate` graph: topological
+batches (parallel levels), per-task subtree context, plus conflict and cycle
+pre-detection. Intended for a parent agent that fans out subagents.
+
+```bash
+dotmd-parser plan ./my-skill            # plan(JSON) to stdout
+dotmd-parser plan ./my-skill --ascii    # human-readable view
+dotmd-parser plan ./my-skill --out plan.json
+dotmd-parser plan ./my-skill --strict   # exit 1 on cycles/conflicts (CI)
+```
+
+Each task in the JSON carries a `context` array (the subtree files to hand the
+subagent). Same-batch shared dependencies are reported in `conflicts[]` as
+warnings — the batch stays parallel. Mutual `@delegate` references are reported
+in `cycles[]` and excluded from batches.
+
 ## `dotmd-index.md` — folder overview in a single file
 
 `dotmd-parser dotmd-index <path>` writes `<path>/dotmd-index.md`, a
@@ -268,6 +352,28 @@ dotmd-parser dotmd-index ./docs/ --push-openrag
 **search index** (full-content semantic retrieval). Register OpenRAG's
 MCP server with Claude Code to use both surfaces from the same client.
 
+### Cache-affine order (`--order cache`)
+
+`dotmd-index --order cache` lists the `## Files` section with the
+least-frequently-changed files first (estimated from git history), so the
+generated `dotmd-index.md` keeps a stable prefix across regenerations — better
+KV-cache reuse for LLMs that read it. Default `--order alpha` is unchanged.
+
+```bash
+dotmd-parser dotmd-index ./skill --order cache
+dotmd-parser dotmd-index ./skill --order cache --stdout
+```
+
+Measure the effect with `stability` (compare two generations):
+
+```bash
+dotmd-parser stability old-index.md new-index.md          # prefix stable: 42/50 lines (0.84)
+dotmd-parser stability old-index.md new-index.md --json
+```
+
+Outside a git repo (or for untracked files) frequency is treated as 0, so
+`cache` degrades gracefully to alphabetical order.
+
 ## `analyze` — AI-assisted dependency detection
 
 Use when a folder of markdown has **no explicit directives yet**. `analyze`

{dotmd_parser-0.6.2 → dotmd_parser-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dotmd-parser"
-version = "0.6.2"
+version = "0.9.0"
 description = "Dependency graph parser, single-file folder index (dotmd-index.md), and AI analyzer for .md skill files — parse @include/@delegate/@ref directives, build graphs, resolve templates, generate RAG-friendly overviews, and ingest into OpenRAG"
 requires-python = ">=3.10"
 license = "MIT"

{dotmd_parser-0.6.2 → dotmd_parser-0.9.0}/src/dotmd_parser/__init__.py

@@ -10,7 +10,7 @@ API:
     from dotmd_parser import digest, tree, affects
 """
 
-__version__ = "0.6.2"
+__version__ = "0.9.0"
 
 from dotmd_parser.parser import (
     build_graph,
@@ -70,7 +70,43 @@ from dotmd_parser.index_md import (
     DEFAULT_INDEX_FILENAME,
     INDEX_MD_SCHEMA,
 )
+from dotmd_parser.cache_order import (
+    git_change_counts,
+    order_key,
+    prefix_stability,
+)
+from dotmd_parser.ledger import (
+    append_event,
+    read_events,
+    active_tags,
+    static_tags,
+    all_active_tags,
+    risk_level,
+    risk_report,
+    default_ledger_path,
+    RISK_TAGS,
+    HIGH_TAGS,
+)
+from dotmd_parser.checks import (
+    run_checks,
+    summarize,
+    exit_code,
+    format_text,
+    format_json,
+    format_sarif,
+    CHECK_SCHEMA,
+)
 from dotmd_parser.openrag import push_to_openrag
+from dotmd_parser.scan import (
+    scan_content,
+    DEFAULT_RULES,
+    OPTIONAL_RULES,
+    ALL_RULES,
+)
+from dotmd_parser.plan import (
+    build_plan,
+    render_ascii,
+)
 
 __all__ = [
     "__version__",
@@ -126,6 +162,37 @@ __all__ = [
     "extract_frontmatter",
     "DEFAULT_INDEX_FILENAME",
     "INDEX_MD_SCHEMA",
+    # cache_order
+    "git_change_counts",
+    "order_key",
+    "prefix_stability",
+    # ledger
+    "append_event",
+    "read_events",
+    "active_tags",
+    "static_tags",
+    "all_active_tags",
+    "risk_level",
+    "risk_report",
+    "default_ledger_path",
+    "RISK_TAGS",
+    "HIGH_TAGS",
+    # checks
+    "run_checks",
+    "summarize",
+    "exit_code",
+    "format_text",
+    "format_json",
+    "format_sarif",
+    "CHECK_SCHEMA",
     # openrag
     "push_to_openrag",
+    # scan
+    "scan_content",
+    "DEFAULT_RULES",
+    "OPTIONAL_RULES",
+    "ALL_RULES",
+    # plan
+    "build_plan",
+    "render_ascii",
 ]

dotmd_parser-0.9.0/src/dotmd_parser/cache_order.py

@@ -0,0 +1,60 @@
+"""
+dotmd-parser — cache-affine ordering helpers.
+
+Estimates per-file change frequency from git history (with a safe fallback)
+and provides an ordering key that puts low-frequency files first, so the
+`dotmd-index.md` body prefix stays stable across regenerations (KV-cache
+friendly). Also a prefix-stability metric. Pure stdlib; git via subprocess.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def git_change_counts(root: str | Path) -> dict[str, int]:
+    """Return {rel_posix: commit_count} from git history; {} when unavailable."""
+    if shutil.which("git") is None:
+        return {}
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), "-c", "core.quotepath=false",
+             "log", "--format=", "--name-only", "--relative", "--", "."],
+            capture_output=True,
+            text=True,
+        )
+    except OSError:
+        return {}
+    if result.returncode != 0:
+        return {}
+    counts: dict[str, int] = {}
+    for line in result.stdout.splitlines():
+        rel = line.strip()
+        if rel:
+            counts[rel] = counts.get(rel, 0) + 1
+    return counts
+
+
+def order_key(rel: str, counts: dict[str, int]) -> tuple[int, str]:
+    """Sort key: low change-count first, path-ascending tiebreak."""
+    return (counts.get(rel, 0), rel)
+
+
+def prefix_stability(old_text: str, new_text: str) -> dict:
+    """Measure how much of `new_text`'s leading lines match `old_text`."""
+    old_lines = old_text.split("\n")
+    new_lines = new_text.split("\n")
+    common = 0
+    for old_line, new_line in zip(old_lines, new_lines):
+        if old_line == new_line:
+            common += 1
+        else:
+            break
+    total_new = len(new_lines)
+    return {
+        "common_prefix_lines": common,
+        "new_lines": total_new,
+        "ratio": round(common / max(total_new, 1), 4),
+    }

dotmd_parser-0.9.0/src/dotmd_parser/checks.py

@@ -0,0 +1,233 @@
+"""
+dotmd-parser — guidance health checks (deterministic CI gate).
+
+Consumes a compact index (from `index.build_index` / `index.load_index`) and
+produces a flat list of Finding dicts, rendered as text / JSON / SARIF. Pure,
+stdlib-only, no LLM. The raw graph / parser are not touched.
+
+Finding shape:
+    {"rule": str, "severity": "error"|"warning", "path": str,
+     "message": str, "line": int | None}
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+CHECK_SCHEMA = "dotmd-check/v1"
+
+_GRAPH_WARNING_RULES = {
+    "depth_exceeded": "depth-exceeded",
+    "read_error": "read-error",
+}
+
+
+def _finding(rule: str, severity: str, path: str, message: str,
+             line: int | None = None) -> dict:
+    return {"rule": rule, "severity": severity, "path": path,
+            "message": message, "line": line}
+
+
+def _circular_findings(index: dict) -> list[dict]:
+    """One error finding per recorded cycle message (path unknown → '')."""
+    return [
+        _finding("circular", "error", "", msg)
+        for msg in index.get("cycles", [])
+    ]
+
+
+def _missing_findings(index: dict) -> list[dict]:
+    """One error finding per missing referenced file."""
+    return [
+        _finding("missing-reference", "error", rel,
+                 "referenced file does not exist")
+        for rel in index.get("missing", [])
+    ]
+
+
+def _graph_warning_findings(index: dict) -> list[dict]:
+    """Promote depth_exceeded / read_error graph warnings to error findings."""
+    out: list[dict] = []
+    for warning in index.get("warnings", []):
+        rule = _GRAPH_WARNING_RULES.get(warning.get("type", ""))
+        if rule is None:
+            continue
+        out.append(_finding(rule, "error", warning.get("path", ""),
+                            warning.get("message", "")))
+    return out
+
+
+def _placeholder_findings(index: dict) -> list[dict]:
+    """One warning finding per unresolved {{var}} (sorted by path, var)."""
+    out: list[dict] = []
+    files = index.get("files", {})
+    for rel in sorted(files):
+        for var in sorted(files[rel].get("placeholders", []) or []):
+            out.append(_finding(
+                "unresolved-placeholder", "warning", rel,
+                f"unresolved placeholder: {{{{{var}}}}}",
+            ))
+    return out
+
+
+_EXPLICIT_DIRECTIVE_TYPES = {"include", "ref", "delegate"}
+
+
+def _conflicting_directive_findings(index: dict) -> list[dict]:
+    """Warn when a source reaches one target via ≥2 distinct explicit types."""
+    out: list[dict] = []
+    files = index.get("files", {})
+    for rel in sorted(files):
+        by_target: dict[str, set[str]] = {}
+        for dep in files[rel].get("deps", []):
+            dtype = dep.get("type", "")
+            if dtype not in _EXPLICIT_DIRECTIVE_TYPES:
+                continue
+            target = dep.get("to", "")
+            if not target:
+                continue
+            by_target.setdefault(target, set()).add(dtype)
+        for target in sorted(by_target):
+            types = by_target[target]
+            if len(types) >= 2:
+                joined = ", ".join(sorted(types))
+                out.append(_finding(
+                    "conflicting-directive", "warning", rel,
+                    f"{target} is referenced by multiple directive types ({joined})",
+                ))
+    return out
+
+
+def _orphan_findings(index: dict, root: str | None) -> list[dict]:
+    """Warn about .md files on disk that no graph node references."""
+    if root is None:
+        return []
+    base = Path(root)
+    if base.is_file():
+        base = base.parent
+    if not base.is_dir():
+        return []
+    node_set = set(index.get("files", {}).keys())
+    out: list[dict] = []
+    for path in sorted(base.rglob("*.md")):
+        rel_path = path.relative_to(base)
+        if any(part.startswith(".") for part in rel_path.parts):
+            continue
+        rel = rel_path.as_posix()
+        if "node_modules" in rel:
+            continue
+        if not path.is_file():
+            continue
+        if rel not in node_set:
+            out.append(_finding("orphan-file", "warning", rel,
+                               "file is not referenced by any node"))
+    return out
+
+
+def run_checks(index: dict, root: str | None = None,
+               enable_orphans: bool = False) -> list[dict]:
+    """Run all enabled checks and return a flat list of findings."""
+    findings: list[dict] = []
+    findings += _circular_findings(index)
+    findings += _missing_findings(index)
+    findings += _graph_warning_findings(index)
+    findings += _placeholder_findings(index)
+    findings += _conflicting_directive_findings(index)
+    if enable_orphans:
+        findings += _orphan_findings(index, root)
+    return findings
+
+
+def summarize(findings: list[dict]) -> dict:
+    """Count findings by severity."""
+    errors = sum(1 for f in findings if f.get("severity") == "error")
+    warnings = sum(1 for f in findings if f.get("severity") == "warning")
+    return {"errors": errors, "warnings": warnings}
+
+
+def exit_code(findings: list[dict], fail_on: str) -> int:
+    """Map findings to a CI exit code per the fail_on threshold."""
+    counts = summarize(findings)
+    if fail_on == "never":
+        return 0
+    if fail_on == "warning":
+        return 1 if (counts["errors"] or counts["warnings"]) else 0
+    # default: "error"
+    return 1 if counts["errors"] else 0
+
+
+def format_text(findings: list[dict], index: dict) -> str:
+    """Render findings as a backward-compatible text summary + detail lines."""
+    stats = index.get("stats", {})
+    counts = summarize(findings)
+    lines = [
+        f"{stats.get('files', 0)} files, {stats.get('edges', 0)} edges — "
+        f"errors:{counts['errors']} warnings:{counts['warnings']}"
+    ]
+    for f in findings:
+        loc = f.get("path") or "-"
+        lines.append(
+            f"  [{f['severity'].upper()}] {f['rule']}: {loc} — {f['message']}"
+        )
+    return "\n".join(lines)
+
+
+def format_json(findings: list[dict], index: dict) -> str:
+    """Render findings as dotmd-check/v1 JSON."""
+    stats = index.get("stats", {})
+    counts = summarize(findings)
+    payload = {
+        "schema": CHECK_SCHEMA,
+        "root": index.get("root", ""),
+        "stats": {
+            "files": stats.get("files", 0),
+            "edges": stats.get("edges", 0),
+            "errors": counts["errors"],
+            "warnings": counts["warnings"],
+        },
+        "findings": findings,
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _camel(rule_id: str) -> str:
+    parts = rule_id.split("-")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def format_sarif(findings: list[dict], index: dict) -> str:
+    """Render findings as SARIF 2.1.0 JSON (for GitHub code scanning)."""
+    from dotmd_parser import __version__  # local import avoids cycle at import time
+
+    rules: dict[str, dict] = {}
+    results: list[dict] = []
+    for f in findings:
+        rule_id = f["rule"]
+        rules.setdefault(rule_id, {"id": rule_id, "name": _camel(rule_id)})
+        result: dict = {
+            "ruleId": rule_id,
+            "level": f["severity"],
+            "message": {"text": f["message"]},
+        }
+        if f.get("path"):
+            physical: dict = {"artifactLocation": {"uri": f["path"]}}
+            if f.get("line"):
+                physical["region"] = {"startLine": f["line"]}
+            result["locations"] = [{"physicalLocation": physical}]
+        results.append(result)
+
+    sarif = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {"driver": {
+                "name": "dotmd-parser",
+                "informationUri": "https://github.com/dotmd-projects/dotmd-parser",
+                "version": __version__,
+                "rules": list(rules.values()),
+            }},
+            "results": results,
+        }],
+    }
+    return json.dumps(sarif, ensure_ascii=False, indent=2)