rbtr-lang-markdown 2026.7.0.dev0__py3-none-any.whl

rbtr_lang_markdown/__init__.py

@@ -0,0 +1 @@
+"""Markdown language plugin package."""

rbtr_lang_markdown/injections.scm

@@ -0,0 +1,4 @@
+; Fenced code blocks: the info string names the embedded language.
+(fenced_code_block
+  (info_string (language) @injection.language)
+  (code_fence_content) @injection.content)

rbtr_lang_markdown/links.scm

@@ -0,0 +1 @@
+(inline_link (link_destination) @dest)

rbtr_lang_markdown/plugin.py

@@ -0,0 +1,260 @@
+"""Markdown language plugin.
+
+Splits Markdown by heading hierarchy using tree-sitter.  Headed
+sections produce one `doc_section` chunk per heading, containing
+the heading and its direct content (excluding nested subsections).
+Headingless documents fall back to `chunk_plaintext`.
+
+Extracted chunks::
+
+    # Title                         → doc_section "Title", scope ""
+    Intro text.                       (content: heading + intro)
+
+    ## Section A                    → doc_section "Section A", scope "Title"
+    Body A.                           (content: heading + body, excludes
+                                       child sections)
+
+    First paragraph.                → raw_chunk (plaintext fallback)
+    Second paragraph.               → raw_chunk
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+from tree_sitter import Language, Parser, Query, QueryCursor
+
+from rbtr.index.identity import make_chunk_id
+from rbtr.index.models import Chunk, ChunkKind, ImportMeta
+from rbtr.languages.chunks import chunk_plaintext
+from rbtr.languages.registration import LanguageRegistration, load_query
+
+if TYPE_CHECKING:
+    from tree_sitter import Node, Range
+
+# URL schemes that indicate external links (not cross-references).
+_EXTERNAL_SCHEMES = ("http://", "https://", "mailto:", "ftp://")
+
+# Block-level query: captures headed sections.
+_SECTION_QUERY = load_query(__package__, "sections")
+
+# Injection query: a fenced code block delegates its content to the language
+# named in the fence's info string (```python, ```sh). The info-string name
+# is captured dynamically and resolved to a language id by the runner.
+
+
+# ── Chunking ─────────────────────────────────────────────────────────
+
+
+def _has_headings(root: Node) -> bool:
+    """Return True if any section in the tree has an atx_heading."""
+    for child in root.children:
+        if child.type == "section":
+            if any(gc.type == "atx_heading" for gc in child.children):
+                return True
+            if _has_headings(child):
+                return True
+    return False
+
+
+def _section_depth(node: Node) -> int:
+    """Count ancestor nodes of the same type.
+
+    In the tree-sitter markdown grammar, sections nest:
+    a `## Sub` section is a child `section` node of the
+    `# Top` section.  The depth (number of same-typed
+    ancestors) maps directly to the heading level minus
+    one: depth 0 = `#`, depth 1 = `##`, etc.
+    """
+    depth = 0
+    ancestor = node.parent
+    while ancestor is not None:
+        if ancestor.type == node.type:
+            depth += 1
+        ancestor = ancestor.parent
+    return depth
+
+
+def _section_own_content(node: Node, content_bytes: bytes) -> str:
+    """Return the section's own text, excluding nested subsections.
+
+    A parent section's byte span covers its children.  Trimming
+    at the first child of the same type gives us only the
+    heading and the prose that belongs directly to this section.
+    """
+    end_byte = node.end_byte
+    for child in node.children:
+        if child.type == node.type:
+            end_byte = child.start_byte
+            break
+    return content_bytes[node.start_byte : end_byte].decode("utf-8", errors="replace").strip()
+
+
+def _extract_sections(
+    content_bytes: bytes,
+    grammar: Language,
+    file_path: str,
+    blob_sha: str,
+    ranges: list[Range] | None,
+) -> Iterator[Chunk]:
+    """Run the section query and yield one chunk per headed section.
+
+    The tree-sitter markdown grammar represents headings as
+    nested `section` nodes.  This function queries for all
+    sections that contain an `atx_heading` and produces one
+    `doc_section` chunk per match.
+
+    **Scope** is the parent heading chain, built by maintaining
+    a stack of heading names indexed by depth.  When a section
+    at depth *d* is encountered, the stack is truncated to *d*
+    entries (popping deeper headings from a previous branch),
+    the current scope is read from the remaining stack, and
+    the new heading is pushed.
+
+    **Content** is trimmed to exclude nested subsections — see
+    `_section_own_content`.
+    """
+    query = Query(grammar, _SECTION_QUERY)
+    parser = Parser(grammar)
+    if ranges is not None:
+        parser.included_ranges = ranges
+    tree = parser.parse(content_bytes)
+    matches = QueryCursor(query).matches(tree.root_node)
+
+    # Heading names indexed by depth.  Tracks the current
+    # branch of the heading tree so we can reconstruct the
+    # scope ("Top::Mid") for each section.
+    scope_stack: list[str] = []
+
+    for _pattern_idx, capture_dict in matches:
+        section_nodes = capture_dict.get("doc_section", [])
+        name_nodes = capture_dict.get("_section_name", [])
+        if not section_nodes or not name_nodes:
+            continue
+
+        node = section_nodes[0]
+        name = name_nodes[0].text.decode("utf-8", errors="replace") if name_nodes[0].text else ""
+
+        # Maintain the scope stack: pop back to this section's
+        # depth, read scope, then push the current heading.
+        depth = _section_depth(node)
+        while len(scope_stack) > depth:
+            scope_stack.pop()
+        scope_segments = list(scope_stack)
+        scope_stack.append(name)
+
+        text = _section_own_content(node, content_bytes)
+        if not text:
+            continue
+
+        line_start = node.start_point[0] + 1
+        yield Chunk.model_validate(
+            {
+                "blob_sha": blob_sha,
+                "file_path": file_path,
+                "kind": ChunkKind.DOC_SECTION,
+                "name": name,
+                "scope": scope_segments,
+                "language": "markdown",
+                "content": text,
+                "line_start": line_start,
+                "line_end": node.end_point[0] + 1,
+            }
+        )
+
+
+def chunk_markdown(
+    file_path: str,
+    blob_sha: str,
+    content: str,
+    grammar: Language,
+    ranges: list[Range] | None = None,
+) -> Iterator[Chunk]:
+    """Split Markdown by heading hierarchy using tree-sitter."""
+    if not content.strip():
+        return
+
+    content_bytes = content.encode("utf-8")
+    parser = Parser(grammar)
+    if ranges is not None:
+        parser.included_ranges = ranges
+    tree = parser.parse(content_bytes)
+
+    if _has_headings(tree.root_node):
+        yield from _extract_sections(content_bytes, grammar, file_path, blob_sha, ranges)
+    else:
+        yield from chunk_plaintext(file_path, blob_sha, content)
+
+    # Extract local links as IMPORT chunks using the inline parser.
+    yield from _extract_links(content_bytes, file_path, blob_sha, ranges)
+
+
+# ── Link extraction ──────────────────────────────────────────────────
+
+_LINK_QUERY = load_query(__package__, "links")
+
+
+def _extract_links(
+    content_bytes: bytes,
+    file_path: str,
+    blob_sha: str,
+    ranges: list[Range] | None,
+) -> Iterator[Chunk]:
+    """Extract local links as IMPORT chunks using the inline parser.
+
+    Parses the full content with `tree_sitter_markdown.inline_language()`
+    and queries for `inline_link` nodes.  External URLs and same-file
+    fragment-only links are skipped.
+    """
+    import tree_sitter_markdown  # deferred: heavy native lib
+
+    inline_lang = Language(tree_sitter_markdown.inline_language())
+    inline_parser = Parser(inline_lang)
+    if ranges is not None:
+        inline_parser.included_ranges = ranges
+    inline_tree = inline_parser.parse(content_bytes)
+
+    query = Query(inline_lang, _LINK_QUERY)
+    for _pattern_idx, captures in QueryCursor(query).matches(inline_tree.root_node):
+        for dest_node in captures.get("dest", []):
+            if dest_node.text is None:
+                continue
+            dest = dest_node.text.decode("utf-8", errors="replace")
+
+            # Skip external URLs and fragment-only anchors.
+            if any(dest.startswith(s) for s in _EXTERNAL_SCHEMES) or dest.startswith("#"):
+                continue
+
+            # Split path#fragment.
+            module = dest
+            names = ""
+            if "#" in dest:
+                module, names = dest.rsplit("#", 1)
+
+            yield Chunk(
+                id=make_chunk_id(file_path, blob_sha, f"link:{dest}", dest_node.start_point[0]),
+                blob_sha=blob_sha,
+                file_path=file_path,
+                kind=ChunkKind.IMPORT,
+                name=dest,
+                scope="",
+                content=dest,
+                metadata=ImportMeta(module=module, names=names),
+                line_start=dest_node.start_point[0] + 1,
+                line_end=dest_node.end_point[0] + 1,
+            )
+
+
+# ── Plugin ───────────────────────────────────────────────────────────
+
+
+markdown = LanguageRegistration(
+    id="markdown",
+    extensions=frozenset({".md"}),
+    grammar_module="tree_sitter_markdown",
+    injection_query=load_query(__package__, "injections"),
+    extraction_serial=4,
+)
+
+markdown.chunker(chunk_markdown)

rbtr_lang_markdown/sections.scm

@@ -0,0 +1,3 @@
+(section
+  (atx_heading
+    (inline) @_section_name)) @doc_section

rbtr_lang_markdown/tests/__snapshots__/test_samples/test_edges_match_snapshot.json

@@ -0,0 +1,5 @@
+[
+  "markdown.md::api.md#format-greeting -> api.md::format-greeting [documents]",
+  "markdown.md::config.md -> config.md::Configuration [documents]",
+  "markdown.md::locales.md -> locales.md::Locales [documents]"
+]

rbtr_lang_markdown/tests/__snapshots__/test_samples/test_extraction_matches_snapshot.json

@@ -0,0 +1,452 @@
+[
+  {
+    "id": "4c81fa35133b40f2",
+    "blob_sha": "sha1",
+    "file_path": "api.md",
+    "kind": "doc_section",
+    "name": "API",
+    "scope": "",
+    "language": "markdown",
+    "content": "# API",
+    "line_start": 1,
+    "line_end": 24,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "31926f465277bc3a",
+    "blob_sha": "sha1",
+    "file_path": "api.md",
+    "kind": "doc_section",
+    "name": "format-greeting",
+    "scope": "API",
+    "language": "markdown",
+    "content": "## format-greeting\n\nFormats a greeting for a name.\n\nCall it from Python:\n\n```python\nfrom greeter import format_greeting\n\n\ndef demo() -> str:\n    return format_greeting(\"Ada\")\n```\n\nOr wrap it in a shell helper:\n\n```sh\ngreet() {\n  format-greeting \"$1\"\n}\n```",
+    "line_start": 3,
+    "line_end": 24,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "a506206919841452",
+    "blob_sha": "sha1",
+    "file_path": "api.md",
+    "kind": "import",
+    "name": "from greeter import format_greeting",
+    "scope": "",
+    "language": "python",
+    "content": "from greeter import format_greeting",
+    "line_start": 10,
+    "line_end": 10,
+    "metadata": {
+      "module": "greeter",
+      "names": "format_greeting",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "67279506d1545bb8",
+    "blob_sha": "sha1",
+    "file_path": "api.md",
+    "kind": "function",
+    "name": "demo",
+    "scope": "",
+    "language": "python",
+    "content": "def demo() -> str:\n    return format_greeting(\"Ada\")",
+    "line_start": 13,
+    "line_end": 14,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "7a4703203f71b0cf",
+    "blob_sha": "sha1",
+    "file_path": "api.md",
+    "kind": "function",
+    "name": "greet",
+    "scope": "",
+    "language": "bash",
+    "content": "greet() {\n  format-greeting \"$1\"\n}",
+    "line_start": 20,
+    "line_end": 22,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "3ad1924164e7ff92",
+    "blob_sha": "sha1",
+    "file_path": "config.md",
+    "kind": "doc_section",
+    "name": "Configuration",
+    "scope": "",
+    "language": "markdown",
+    "content": "# Configuration\n\nGreeter configuration options.",
+    "line_start": 1,
+    "line_end": 4,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "a07c6280b6b72cff",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "doc_section",
+    "name": "Embedding",
+    "scope": "",
+    "language": "markdown",
+    "content": "# Embedding\n\nExamples embedded in the docs, each extracted in its own language —\nincluding code nested two levels deep.\n\nThe greeter config, in YAML:\n\n```yaml\nservice: greeter\nlocales:\n  - en\n  - fr\n```\n\nThe same in TOML:\n\n```toml\n[service]\nname = \"greeter\"\n```\n\nEmbedded in a page — the stylesheet is an import and the inline script is\nextracted as JavaScript:\n\n```html\n<head>\n  <link rel=\"stylesheet\" href=\"greeter.css\">\n</head>\n<body>\n  <main>\n    <script>\n      function mount() {\n        return greet(\"Ada\");\n      }\n    </script>\n  </main>\n</body>\n```\n\nAnd a component — Markdown delegates to the Svelte chunker, which in turn\ndelegates its `<script>` to TypeScript and its `<style>` to SCSS:\n\n```svelte\n<script lang=\"ts\">\n  export let name: string;\n\n  function shout(): string {\n    return name.toUpperCase();\n  }\n</script>\n\n<h1>Hello {name}</h1>\n\n<style lang=\"scss\">\n  h1 {\n    color: $brand;\n  }\n</style>\n```",
+    "line_start": 1,
+    "line_end": 60,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "f7b93e9d583f37fb",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "config_key",
+    "name": "service",
+    "scope": "",
+    "language": "yaml",
+    "content": "service: greeter",
+    "line_start": 9,
+    "line_end": 9,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "ee32c29d4bb258d2",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "config_key",
+    "name": "locales",
+    "scope": "",
+    "language": "yaml",
+    "content": "locales:\n  - en\n  - fr\n",
+    "line_start": 10,
+    "line_end": 13,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "720abd335b592da1",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "config_key",
+    "name": "service",
+    "scope": "",
+    "language": "toml",
+    "content": "[service]\nname = \"greeter\"\n",
+    "line_start": 18,
+    "line_end": 20,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "dde01fdcfbaf35fe",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "doc_section",
+    "name": "head",
+    "scope": "",
+    "language": "html",
+    "content": "<head>\n  <link rel=\"stylesheet\" href=\"greeter.css\">\n</head>",
+    "line_start": 26,
+    "line_end": 28,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "237cf8cd884f0889",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "import",
+    "name": "<link rel=\"stylesheet\" href=\"greeter.css\">",
+    "scope": "",
+    "language": "html",
+    "content": "<link rel=\"stylesheet\" href=\"greeter.css\">\n",
+    "line_start": 27,
+    "line_end": 28,
+    "metadata": {
+      "module": "greeter.css",
+      "names": "",
+      "dots": "",
+      "language_hint": "css"
+    }
+  },
+  {
+    "id": "648732774bcd70e1",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "doc_section",
+    "name": "body",
+    "scope": "",
+    "language": "html",
+    "content": "<body>\n  <main>\n    <script>\n      function mount() {\n        return greet(\"Ada\");\n      }\n    </script>\n  </main>\n</body>",
+    "line_start": 29,
+    "line_end": 37,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "d5a2a0b511006ed9",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "doc_section",
+    "name": "main",
+    "scope": "",
+    "language": "html",
+    "content": "<main>\n    <script>\n      function mount() {\n        return greet(\"Ada\");\n      }\n    </script>\n  </main>",
+    "line_start": 30,
+    "line_end": 36,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "3c90b98fdfca2398",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "function",
+    "name": "mount",
+    "scope": "",
+    "language": "javascript",
+    "content": "function mount() {\n        return greet(\"Ada\");\n      }",
+    "line_start": 32,
+    "line_end": 34,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "fa22ee7555d55068",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "doc_section",
+    "name": "embedding",
+    "scope": "",
+    "language": "svelte",
+    "content": "<h1>Hello {name}</h1>",
+    "line_start": 52,
+    "line_end": 52,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "4447dc40f1fe4853",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "function",
+    "name": "shout",
+    "scope": "",
+    "language": "typescript",
+    "content": "function shout(): string {\n    return name.toUpperCase();\n  }",
+    "line_start": 47,
+    "line_end": 49,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "ff44cea1c6365f3c",
+    "blob_sha": "sha1",
+    "file_path": "embedding.md",
+    "kind": "class",
+    "name": "h1",
+    "scope": "",
+    "language": "scss",
+    "content": "h1 {\n    color: $brand;\n  }",
+    "line_start": 55,
+    "line_end": 57,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "28a545073daa5946",
+    "blob_sha": "sha1",
+    "file_path": "locales.md",
+    "kind": "doc_section",
+    "name": "Locales",
+    "scope": "",
+    "language": "markdown",
+    "content": "# Locales\n\nSupported locales: en, fr.",
+    "line_start": 1,
+    "line_end": 4,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "e3e544e26089db67",
+    "blob_sha": "sha1",
+    "file_path": "markdown.md",
+    "kind": "doc_section",
+    "name": "Greeter",
+    "scope": "",
+    "language": "markdown",
+    "content": "# Greeter\n\nA small library for formatting greetings for named recipients.",
+    "line_start": 1,
+    "line_end": 17,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "0f8107d00ba18621",
+    "blob_sha": "sha1",
+    "file_path": "markdown.md",
+    "kind": "doc_section",
+    "name": "Usage",
+    "scope": "Greeter",
+    "language": "markdown",
+    "content": "## Usage\n\nConfigure it via [the config file](config.md), then call the\n[format helper](api.md#format-greeting).\n\nFor background, see [an external guide](https://example.com), which is\nnot treated as a cross-reference.",
+    "line_start": 5,
+    "line_end": 17,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "14b9d728e5d4cd68",
+    "blob_sha": "sha1",
+    "file_path": "markdown.md",
+    "kind": "doc_section",
+    "name": "Locales",
+    "scope": "Greeter::Usage",
+    "language": "markdown",
+    "content": "### Locales\n\nSupported locales are documented in [the locales table](locales.md).\nJump to [the usage section](#usage) for examples.",
+    "line_start": 13,
+    "line_end": 17,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "b12622bb4964947e",
+    "blob_sha": "sha1",
+    "file_path": "markdown.md",
+    "kind": "import",
+    "name": "config.md",
+    "scope": "",
+    "language": "markdown",
+    "content": "config.md",
+    "line_start": 7,
+    "line_end": 7,
+    "metadata": {
+      "module": "config.md",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "4b065fa2fc20ac27",
+    "blob_sha": "sha1",
+    "file_path": "markdown.md",
+    "kind": "import",
+    "name": "api.md#format-greeting",
+    "scope": "",
+    "language": "markdown",
+    "content": "api.md#format-greeting",
+    "line_start": 8,
+    "line_end": 8,
+    "metadata": {
+      "module": "api.md",
+      "names": "format-greeting",
+      "dots": "",
+      "language_hint": ""
+    }
+  },
+  {
+    "id": "2b980c3ee2e79b0c",
+    "blob_sha": "sha1",
+    "file_path": "markdown.md",
+    "kind": "import",
+    "name": "locales.md",
+    "scope": "",
+    "language": "markdown",
+    "content": "locales.md",
+    "line_start": 15,
+    "line_end": 15,
+    "metadata": {
+      "module": "locales.md",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    }
+  }
+]

rbtr_lang_markdown/tests/cases_extraction.py

@@ -0,0 +1,82 @@
+"""Markdown extraction test cases (heading hierarchy → doc sections)."""
+
+from __future__ import annotations
+
+from pytest_cases import case
+
+type SymbolCase = tuple[str, str, list[tuple[str, str, str]]]
+
+
+@case(tags=["symbol"])
+def case_md_splits_by_heading() -> SymbolCase:
+    """Markdown heading hierarchy."""
+    src = """\
+# Title
+
+Intro text.
+
+## Section A
+
+Body A.
+
+## Section B
+
+Body B.
+"""
+    return (
+        "markdown",
+        src,
+        [
+            ("doc_section", "Title", ""),
+            ("doc_section", "Section A", "Title"),
+            ("doc_section", "Section B", "Title"),
+        ],
+    )
+
+
+@case(tags=["symbol"])
+def case_md_scope_chain() -> SymbolCase:
+    """Nested heading scope."""
+    src = """\
+# Top
+
+## Mid
+
+### Deep
+
+Content here.
+"""
+    return "markdown", src, [("doc_section", "Deep", "Top::Mid")]
+
+
+@case(tags=["symbol"])
+def case_md_same_name_under_different_parents() -> SymbolCase:
+    """Same-named sections under different parents get distinct scopes.
+
+    Two `Overview` subsections — one under `A`, one under `B` — are
+    `(doc_section, Overview, A)` and `(doc_section, Overview, B)`. Without
+    the full heading path they would collide on identity; addressing
+    keeps them apart.
+    """
+    src = """\
+# A
+
+Alpha intro.
+
+## Overview
+
+Alpha overview.
+
+# B
+
+Beta intro.
+
+## Overview
+
+Beta overview.
+"""
+    return (
+        "markdown",
+        src,
+        [("doc_section", "Overview", "A"), ("doc_section", "Overview", "B")],
+    )

rbtr_lang_markdown/tests/samples/markdown/api.md

@@ -0,0 +1,23 @@
+# API
+
+## format-greeting
+
+Formats a greeting for a name.
+
+Call it from Python:
+
+```python
+from greeter import format_greeting
+
+
+def demo() -> str:
+    return format_greeting("Ada")
+```
+
+Or wrap it in a shell helper:
+
+```sh
+greet() {
+  format-greeting "$1"
+}
+```

rbtr_lang_markdown/tests/samples/markdown/config.md

@@ -0,0 +1,3 @@
+# Configuration
+
+Greeter configuration options.

rbtr_lang_markdown/tests/samples/markdown/embedding.md

@@ -0,0 +1,59 @@
+# Embedding
+
+Examples embedded in the docs, each extracted in its own language —
+including code nested two levels deep.
+
+The greeter config, in YAML:
+
+```yaml
+service: greeter
+locales:
+  - en
+  - fr
+```
+
+The same in TOML:
+
+```toml
+[service]
+name = "greeter"
+```
+
+Embedded in a page — the stylesheet is an import and the inline script is
+extracted as JavaScript:
+
+```html
+<head>
+  <link rel="stylesheet" href="greeter.css">
+</head>
+<body>
+  <main>
+    <script>
+      function mount() {
+        return greet("Ada");
+      }
+    </script>
+  </main>
+</body>
+```
+
+And a component — Markdown delegates to the Svelte chunker, which in turn
+delegates its `<script>` to TypeScript and its `<style>` to SCSS:
+
+```svelte
+<script lang="ts">
+  export let name: string;
+
+  function shout(): string {
+    return name.toUpperCase();
+  }
+</script>
+
+<h1>Hello {name}</h1>
+
+<style lang="scss">
+  h1 {
+    color: $brand;
+  }
+</style>
+```

rbtr_lang_markdown/tests/samples/markdown/locales.md

@@ -0,0 +1,3 @@
+# Locales
+
+Supported locales: en, fr.

rbtr_lang_markdown/tests/samples/markdown/markdown.md

@@ -0,0 +1,16 @@
+# Greeter
+
+A small library for formatting greetings for named recipients.
+
+## Usage
+
+Configure it via [the config file](config.md), then call the
+[format helper](api.md#format-greeting).
+
+For background, see [an external guide](https://example.com), which is
+not treated as a cross-reference.
+
+### Locales
+
+Supported locales are documented in [the locales table](locales.md).
+Jump to [the usage section](#usage) for examples.

rbtr_lang_markdown/tests/test_extraction.py

@@ -0,0 +1,201 @@
+"""Markdown extraction tests.
+
+The symbol cases (`cases_extraction.py`) drive the shared heading-hierarchy
+check; the functions below pin Markdown's chunker behaviour (section content,
+headingless fallback), fenced-code injection/delegation, and link extraction.
+"""
+
+from __future__ import annotations
+
+from pytest_cases import parametrize_with_cases
+
+from rbtr.git import FileEntry
+from rbtr.index.models import ChunkKind
+from rbtr.languages.extract import extract_file
+
+
+@parametrize_with_cases("lang, source, expected", cases=".cases_extraction", has_tag="symbol")
+def test_extracts_expected_symbols(lang: str, source: str, expected: list) -> None:
+    """Each expected (kind, name, scope) tuple appears in the output."""
+    chunks = extract_file(FileEntry("input", "sha1", source.encode()), lang)
+    symbols = [(c.kind, c.name, c.scope) for c in chunks]
+    for exp in expected:
+        assert exp in symbols, f"expected {exp} not found in {symbols}"
+
+
+def test_md_subsection_excluded_from_parent_content() -> None:
+    """Markdown parent chunk excludes child section content."""
+    src = """\
+# Parent
+
+Parent body.
+
+## Child
+
+Child body.
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    parent = next(c for c in chunks if c.name == "Parent")
+    assert "Child body" not in parent.content
+    assert "Parent body" in parent.content
+
+
+def test_md_headingless_paragraphs() -> None:
+    """Markdown without headings falls back to plaintext chunking."""
+    src = """\
+First paragraph.
+
+Second paragraph.
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    assert len(chunks) >= 1
+    assert all(c.kind == ChunkKind.RAW_CHUNK for c in chunks)
+
+
+def test_md_chunker_target_extracted() -> None:
+    """A chunker-based target (yaml) inside a Markdown fence extracts.
+
+    Query targets (python) already worked; this proves the delegate runs a
+    chunker plugin over the block too, at absolute line numbers.
+    """
+    src = """\
+# Doc
+
+```yaml
+service: greeter
+```
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    yaml_sections = [c for c in chunks if c.language == "yaml"]
+    assert [c.name for c in yaml_sections] == ["service"]
+    assert yaml_sections[0].line_start == 4
+
+
+def test_md_nested_injection_extracts_inner_js() -> None:
+    """Delegation recurses: markdown -> html -> its inline js.
+
+    An HTML block whose HTML contains an inline `<script>` yields both the
+    html chunks and the js function, each at absolute line numbers.
+    """
+    src = """\
+# Doc
+
+```html
+<body>
+  <main>
+    <script>
+      function boot() {
+        return 1;
+      }
+    </script>
+  </main>
+</body>
+```
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    assert "html" in {c.language for c in chunks}
+    js = [c for c in chunks if c.language == "javascript" and c.kind == ChunkKind.FUNCTION]
+    assert [c.name for c in js] == ["boot"]
+    assert js[0].line_start == 7
+
+
+def test_md_unknown_fence_left_unparsed() -> None:
+    """A fence naming a language rbtr has no grammar for is not delegated."""
+    src = """\
+# Doc
+
+```nonexistent
+some content here
+```
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    assert {c.language for c in chunks} == {"markdown"}
+
+
+def test_md_local_link_produces_import() -> None:
+    """Markdown [text](local.md) produces an IMPORT chunk."""
+    src = """\
+# Guide
+
+See [other doc](other.md) for details.
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    imports = [c for c in chunks if c.kind == ChunkKind.IMPORT]
+    assert len(imports) == 1
+    assert imports[0].metadata.module == "other.md"
+
+
+def test_md_link_with_fragment_sets_names() -> None:
+    """Markdown [text](path.md#section) sets module and names."""
+    src = """\
+# Guide
+
+See [API section](api.md#my-function) for the API.
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    imports = [c for c in chunks if c.kind == ChunkKind.IMPORT]
+    assert len(imports) == 1
+    assert imports[0].metadata.module == "api.md"
+    assert imports[0].metadata.names == "my-function"
+
+
+def test_md_relative_link_produces_import() -> None:
+    """Markdown [text](../src/foo.py) with relative path produces import."""
+    src = """\
+# Docs
+
+See [source](../src/foo.py) for details.
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    imports = [c for c in chunks if c.kind == ChunkKind.IMPORT]
+    assert len(imports) == 1
+    assert imports[0].metadata.module == "../src/foo.py"
+
+
+def test_md_external_link_skipped() -> None:
+    """Markdown links to external URLs produce no import chunk."""
+    src = """\
+# Guide
+
+See [example](https://example.com) and [mail](mailto:a@b.com).
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    imports = [c for c in chunks if c.kind == ChunkKind.IMPORT]
+    assert imports == []
+
+
+def test_md_fragment_only_link_skipped() -> None:
+    """Markdown #-only links (same-file anchors) produce no import."""
+    src = """\
+# Guide
+
+See [below](#details) for more.
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    imports = [c for c in chunks if c.kind == ChunkKind.IMPORT]
+    assert imports == []
+
+
+def test_md_multiple_links_in_one_section() -> None:
+    """Multiple links in a single section produce multiple imports."""
+    src = """\
+# Guide
+
+See [a](one.md) and [b](two.py) here.
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    imports = [c for c in chunks if c.kind == ChunkKind.IMPORT]
+    modules = {c.metadata.module for c in imports}
+    assert modules == {"one.md", "two.py"}
+
+
+def test_md_bare_mention_no_import() -> None:
+    """Prose mentioning a symbol name without a link produces no import."""
+    src = """\
+# Guide
+
+Call do_stuff to process the data.
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "markdown")
+    imports = [c for c in chunks if c.kind == ChunkKind.IMPORT]
+    assert imports == []

rbtr_lang_markdown/tests/test_samples.py

@@ -0,0 +1,73 @@
+"""Markdown sample extraction: the `samples/markdown/` project through the real pipeline.
+
+The sample embeds fenced code (python, sh, yaml, toml, html, svelte), delegated to
+those plugins, and links between files, so the snapshot captures the doc sections,
+injected chunks, and cross-file edges.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+from tree_sitter import Parser
+
+from rbtr.git import FileEntry
+from rbtr.index.models import Chunk, ChunkKind, Edge
+from rbtr.languages.edges import build_resolution_map, infer_import_edges
+from rbtr.languages.extract import extract_file
+from rbtr.languages.manager import get_manager
+from rbtr.testing import render_edges
+
+if TYPE_CHECKING:
+    from syrupy.assertion import SnapshotAssertion
+
+
+@pytest.fixture
+def project() -> list[tuple[str, str]]:
+    root = Path(__file__).parent / "samples" / "markdown"
+    return [
+        (str(p.relative_to(root)), p.read_text()) for p in sorted(root.rglob("*")) if p.is_file()
+    ]
+
+
+@pytest.fixture
+def chunks(project: list[tuple[str, str]]) -> list[Chunk]:
+    manager = get_manager()
+    out: list[Chunk] = []
+    for path, text in project:
+        lang = manager.detect_language(path) or "markdown"
+        out.extend(extract_file(FileEntry(path, "sha1", text.encode()), lang))
+    return out
+
+
+@pytest.fixture
+def edges(project: list[tuple[str, str]], chunks: list[Chunk]) -> list[Edge]:
+    manager = get_manager()
+    repo_files = {path for path, _ in project}
+    return infer_import_edges(chunks, repo_files, build_resolution_map(manager))
+
+
+def test_emits_expected_kinds(chunks: list[Chunk]) -> None:
+    """The sample exercises Markdown's doc-section, import, and (injected) function chunks."""
+    kinds = {c.kind for c in chunks}
+    assert {ChunkKind.DOC_SECTION, ChunkKind.IMPORT, ChunkKind.FUNCTION} <= kinds
+
+
+def test_parses_cleanly(project: list[tuple[str, str]]) -> None:
+    manager = get_manager()
+    for path, text in project:
+        grammar = manager.grammar(manager.detect_language(path) or "markdown")
+        assert grammar is not None
+        assert not Parser(grammar).parse(text.encode()).root_node.has_error, path
+
+
+def test_extraction_matches_snapshot(chunks: list[Chunk], snapshot_json: SnapshotAssertion) -> None:
+    assert chunks == snapshot_json
+
+
+def test_edges_match_snapshot(
+    chunks: list[Chunk], edges: list[Edge], snapshot_json: SnapshotAssertion
+) -> None:
+    assert render_edges(edges, chunks) == snapshot_json

rbtr_lang_markdown-2026.7.0.dev0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: rbtr-lang-markdown
+Version: 2026.7.0.dev0
+Summary: rbtr — Markdown language plugin
+License-Expression: MIT
+Requires-Dist: rbtr==2026.7.0.dev0
+Requires-Dist: tree-sitter-markdown
+Requires-Python: >=3.13

rbtr_lang_markdown-2026.7.0.dev0.dist-info/RECORD

@@ -0,0 +1,21 @@
+rbtr_lang_markdown/__init__.py,sha256=weuithB4aHCTq-wPNp_y5ZwjPC1yeou0xULcRyuUFj4,40
+rbtr_lang_markdown/injections.scm,sha256=cLOGbMRML3f8Jzswc2GDBpa-1Gi_zNTxnVQjbRa2xH0,176
+rbtr_lang_markdown/links.scm,sha256=XctZN0F1jK3R25cB3iibwwrToLuKCXkI2OwAUs0PBrc,38
+rbtr_lang_markdown/plugin.py,sha256=RUSmeMZu3Q38SqTE5U1vpk5exyjrEWWg6B3u9hyvXm0,9281
+rbtr_lang_markdown/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rbtr_lang_markdown/sections.scm,sha256=wngkUdNvGv02wG9iAJ4covTbUsYzz4s_w-SsfesmcJU,67
+rbtr_lang_markdown/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rbtr_lang_markdown/tests/__snapshots__/test_samples/test_edges_match_snapshot.json,sha256=Ro7UeECd2OXfodBcTNQOV2f9LmYmqtoD0z0-K-j8mfs,215
+rbtr_lang_markdown/tests/__snapshots__/test_samples/test_extraction_matches_snapshot.json,sha256=-MPiZRLoGpBgtJS6WZOChTA6CHTaZVxeRXyXVMYQICk,11583
+rbtr_lang_markdown/tests/cases_extraction.py,sha256=JQzTn_6WW4SpJQ9YzSgMECso7uYrlulLj2wNxEI5Ej4,1491
+rbtr_lang_markdown/tests/samples/markdown/api.md,sha256=2F5g7PQLcEdKPES47TQca-SVTP3pA31YlfqQkRK56OM,263
+rbtr_lang_markdown/tests/samples/markdown/config.md,sha256=OTgOzfy6xqEd32UC_PTKXRuy1iJjPm6hV2ujJSDZFsc,48
+rbtr_lang_markdown/tests/samples/markdown/embedding.md,sha256=96CmLLZTGmt0_J3ef2UkT-faQUWdwtstEKUGbzu0x7w,924
+rbtr_lang_markdown/tests/samples/markdown/locales.md,sha256=ebMR__v2cXo2bloVrZTF5SJTnXQiuh2-pA7VlcmTh9o,38
+rbtr_lang_markdown/tests/samples/markdown/markdown.md,sha256=--s11aEN37CH13zF9hUlf1wYd1yBK6rx8L52YgfIWLk,426
+rbtr_lang_markdown/tests/test_extraction.py,sha256=Sm-sPwXYMb_KQnNEh9PVZtAVm3Evclove53EtT-7eCo,6172
+rbtr_lang_markdown/tests/test_samples.py,sha256=Dz6tzRtxSjfzqAjgqFyMim1HgIiGlVhEPgMNX8IzXhk,2516
+rbtr_lang_markdown-2026.7.0.dev0.dist-info/WHEEL,sha256=CoDSoyhtC_eO_tlxRYzsTraPv1fPJRXFx91k6ISeAvA,81
+rbtr_lang_markdown-2026.7.0.dev0.dist-info/entry_points.txt,sha256=GMt2XVnJ4yjJuObRxAuF8dLkxUIi1TS_f0YuaN7eZ9I,64
+rbtr_lang_markdown-2026.7.0.dev0.dist-info/METADATA,sha256=B-A33cFRCjtijD9wnHDqi_k__P7DQYzJMB_yeGh4Zwg,232
+rbtr_lang_markdown-2026.7.0.dev0.dist-info/RECORD,,

rbtr_lang_markdown-2026.7.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.28
+Root-Is-Purelib: true
+Tag: py3-none-any

rbtr_lang_markdown-2026.7.0.dev0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[rbtr.languages]
+markdown = rbtr_lang_markdown.plugin:markdown
+