rbtr-lang-bash 2026.9.0.dev1__tar.gz

rbtr_lang_bash-2026.9.0.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Giacometti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rbtr_lang_bash-2026.9.0.dev1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: rbtr-lang-bash
+Version: 2026.9.0.dev1
+Summary: rbtr — Bash language plugin
+Keywords: code-search,code-index,tree-sitter,static-analysis,semantic-search,developer-tools,bash,shell
+Author: Alejandro Giacometti
+Author-email: Alejandro Giacometti <alejandro.giacometti@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Unix Shell
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Dist: rbtr==2026.9.0.dev1
+Requires-Dist: tree-sitter-bash
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/janrito/rbtr
+Project-URL: Repository, https://github.com/janrito/rbtr
+Project-URL: Documentation, https://github.com/janrito/rbtr/tree/main/packages/rbtr-lang-bash#readme
+Project-URL: Issues, https://github.com/janrito/rbtr/issues
+Project-URL: Changelog, https://github.com/janrito/rbtr/releases
+Description-Content-Type: text/markdown
+
+# rbtr-lang-bash
+
+Bash / shell support for [rbtr]. **Default** — installed with
+core `rbtr`, no extra required.
+
+[rbtr]: https://github.com/janrito/rbtr/tree/main/packages/rbtr#readme
+
+## What it ingests
+
+- **Functions** — both `name() { ... }` and `function name { ... }`
+  forms. All functions are top-level (bash has no nesting).
+- **Top-level variable assignments** — `MAX=100`, and `alias` names.
+- **Imports** — `source file` and `. file` commands.
+- **Top-level statements** — every other command, pipeline, conditional and
+  loop at the top level becomes an anonymous **doc-section** chunk. A script
+  that defines nothing is what it does, so `rsync -a ./build/ "$DEST"` is as
+  findable as a function.
+
+Bash has no classes, methods, or module structure, so none are emitted.
+
+## Chunks produced
+
+`scope` is always empty. `name` is the function/variable identifier.
+
+```bash
+deploy() { echo deploying; }   # function "deploy"
+function setup { ...; }         # function "setup"
+MAX=100                         # variable "MAX"
+alias ll="ls -l"                # variable "ll"  (the fused `=` is stripped)
+source ./env.sh                 # import  "./env.sh"
+. /etc/profile                  # import  "/etc/profile"
+```
+
+A leading `#` comment run above a function is attached as its
+documentation; a `#!/bin/bash` shebang attaches to the first function
+only when no blank line separates them.
+
+## Embedded / injected chunks
+
+None. Bash does not embed other languages.
+
+## Grammar & dependencies
+
+Uses the `tree-sitter-bash` grammar. No dependency on other language
+plugins.

rbtr_lang_bash-2026.9.0.dev1/README.md

@@ -0,0 +1,45 @@
+# rbtr-lang-bash
+
+Bash / shell support for [rbtr]. **Default** — installed with
+core `rbtr`, no extra required.
+
+[rbtr]: https://github.com/janrito/rbtr/tree/main/packages/rbtr#readme
+
+## What it ingests
+
+- **Functions** — both `name() { ... }` and `function name { ... }`
+  forms. All functions are top-level (bash has no nesting).
+- **Top-level variable assignments** — `MAX=100`, and `alias` names.
+- **Imports** — `source file` and `. file` commands.
+- **Top-level statements** — every other command, pipeline, conditional and
+  loop at the top level becomes an anonymous **doc-section** chunk. A script
+  that defines nothing is what it does, so `rsync -a ./build/ "$DEST"` is as
+  findable as a function.
+
+Bash has no classes, methods, or module structure, so none are emitted.
+
+## Chunks produced
+
+`scope` is always empty. `name` is the function/variable identifier.
+
+```bash
+deploy() { echo deploying; }   # function "deploy"
+function setup { ...; }         # function "setup"
+MAX=100                         # variable "MAX"
+alias ll="ls -l"                # variable "ll"  (the fused `=` is stripped)
+source ./env.sh                 # import  "./env.sh"
+. /etc/profile                  # import  "/etc/profile"
+```
+
+A leading `#` comment run above a function is attached as its
+documentation; a `#!/bin/bash` shebang attaches to the first function
+only when no blank line separates them.
+
+## Embedded / injected chunks
+
+None. Bash does not embed other languages.
+
+## Grammar & dependencies
+
+Uses the `tree-sitter-bash` grammar. No dependency on other language
+plugins.

rbtr_lang_bash-2026.9.0.dev1/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["uv_build>=0.11.26,<1"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "rbtr_lang_bash"
+
+[tool.uv.sources.rbtr]
+workspace = true
+
+[project]
+name = "rbtr-lang-bash"
+version = "2026.9.0-dev1"
+description = "rbtr — Bash language plugin"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "code-search",
+    "code-index",
+    "tree-sitter",
+    "static-analysis",
+    "semantic-search",
+    "developer-tools",
+    "bash",
+    "shell",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Unix Shell",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing :: Indexing",
+    "Typing :: Typed",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "rbtr==2026.9.0-dev1",
+    "tree-sitter-bash",
+]
+
+[[project.authors]]
+name = "Alejandro Giacometti"
+email = "alejandro.giacometti@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/janrito/rbtr"
+Repository = "https://github.com/janrito/rbtr"
+Documentation = "https://github.com/janrito/rbtr/tree/main/packages/rbtr-lang-bash#readme"
+Issues = "https://github.com/janrito/rbtr/issues"
+Changelog = "https://github.com/janrito/rbtr/releases"
+
+[project.entry-points."rbtr.languages"]
+bash = "rbtr_lang_bash.plugin:bash"
+
+[dependency-groups]
+dev = ["rbtr[test]"]

rbtr_lang_bash-2026.9.0.dev1/pyproject.toml.orig

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["uv_build>=0.11.26,<1"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "rbtr_lang_bash"
+# No source-exclude: the plugin's tests, samples, and snapshots ship
+# with the wheel, and bash.scm ships as package data.
+
+[project]
+name = "rbtr-lang-bash"
+version = "2026.9.0-dev1"
+description = "rbtr — Bash language plugin"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Alejandro Giacometti", email = "alejandro.giacometti@gmail.com" },
+]
+keywords = [
+  "code-search",
+  "code-index",
+  "tree-sitter",
+  "static-analysis",
+  "semantic-search",
+  "developer-tools",
+  "bash",
+  "shell",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Unix Shell",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Text Processing :: Indexing",
+  "Typing :: Typed",
+]
+requires-python = ">=3.13"
+dependencies = [
+  "rbtr==2026.9.0-dev1",
+  "tree-sitter-bash",
+]
+
+[project.urls]
+Homepage = "https://github.com/janrito/rbtr"
+Repository = "https://github.com/janrito/rbtr"
+Documentation = "https://github.com/janrito/rbtr/tree/main/packages/rbtr-lang-bash#readme"
+Issues = "https://github.com/janrito/rbtr/issues"
+Changelog = "https://github.com/janrito/rbtr/releases"
+
+[project.entry-points."rbtr.languages"]
+# The value resolves to the language's `LanguageRegistration` (named by its
+# id) — see the rbtr ARCHITECTURE "External plugins" note.
+bash = "rbtr_lang_bash.plugin:bash"
+
+[tool.uv.sources]
+rbtr = { workspace = true }
+
+[dependency-groups]
+dev = ["rbtr[test]"]

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/__init__.py

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

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/bash.scm

@@ -0,0 +1,50 @@
+; Top-level comments (Bash: single `comment` type).
+(comment) @comment
+
+(function_definition
+  name: (word) @_fn_name) @function
+
+(command
+  name: (command_name
+    (word) @_cmd)
+  .
+  (word) @_import_module
+  (#eq? @_cmd "source")) @import
+
+(command
+  name: (command_name
+    (word) @_cmd)
+  .
+  (word) @_import_module
+  (#eq? @_cmd ".")) @import
+
+(program
+  (variable_assignment
+    name: (variable_name) @_var_name) @variable)
+
+(program
+  (declaration_command
+    (variable_assignment
+      name: (variable_name) @_var_name)) @variable)
+
+(command
+  name: (command_name (word) @_cmd)
+  argument: (concatenation (word) @_var_name)
+  (#eq? @_cmd "alias")
+  (#match? @_var_name "=")) @variable
+
+; A script's top-level statements are what it does, and no name stands
+; for them, so each is an anonymous section located by its lines. A
+; script that defines nothing is still entirely searchable.
+(program
+  (command
+    name: (command_name (word) @_statement)
+    ; `source`, `.` and `alias` are already an import or a variable above.
+    ; One `#not-match?` rather than several `#not-any-of?` arguments, which
+    ; this binding applies only when given exactly one.
+    (#not-match? @_statement "^(source|[.]|alias)$")) @doc_section)
+
+(program
+  [(if_statement) (for_statement) (while_statement) (case_statement)
+   (pipeline) (list) (subshell) (compound_statement) (unset_command)
+   (redirected_statement)] @doc_section)

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/plugin.py

@@ -0,0 +1,64 @@
+"""Bash language plugin.
+
+Provides function extraction only — Bash has no import system,
+class system, or module structure.
+
+Extracted chunks::
+
+    deploy() { echo deploying; }    → function "deploy", scope ""
+    function setup { ... }          → function "setup", scope ""
+    alias ll="ls -l"                → variable "ll", scope ""
+
+No classes or methods are extracted.
+
+An `alias` name parses as one `word` fused with its `=` (`ll=`), which no
+query can split. The `name_extractor` strips the trailing `=`; no other
+bash name ends in one.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rbtr.languages.registration import (
+    LanguageRegistration,
+    NameResolver,
+    QueryExtraction,
+    load_query,
+)
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+
+# ── Query ────────────────────────────────────────────────────────────
+
+
+# ── Plugin ───────────────────────────────────────────────────────────
+
+
+bash = LanguageRegistration(
+    id="bash",
+    extensions=frozenset({".sh", ".bash", ".zsh"}),
+    filenames=frozenset(
+        {
+            "Bashrc",
+            ".bashrc",
+            ".bash_profile",
+            ".zshrc",
+        }
+    ),
+    grammar_module="tree_sitter_bash",
+    extraction=QueryExtraction(
+        query=load_query(__package__, "bash"),
+    ),
+    extraction_serial=5,
+)
+
+
+@bash.name_extractor
+def _strip_alias_eq(
+    resolver: NameResolver, capture_name: str, node: Node, captures: dict[str, list[Node]]
+) -> str:
+    """Default name, with the `=` the grammar fuses onto an alias removed."""
+    return resolver(capture_name, node, captures).rstrip("=")

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/__snapshots__/test_samples/test_edges_match_snapshot.json

@@ -0,0 +1,4 @@
+[
+  "bash.sh::source ./lib/colours.sh -> lib/colours.sh::RED [imports]",
+  "bash.sh::source ./lib/colours.sh -> lib/colours.sh::RESET [imports]"
+]

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/__snapshots__/test_samples/test_extraction_matches_snapshot.json

@@ -0,0 +1,325 @@
+[
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "comment",
+    "name": "",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "#!/usr/bin/env bash\n# Greeter — print greetings for named recipients.\n#\n# Bash has no classes or methods; the plugin extracts functions,\n# top-level variable assignments (including export/declare/readonly),\n# aliases, and source/. imports.",
+    "line_start": 1,
+    "line_end": 6,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "e4307a2c6ea35a81"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "import",
+    "name": "source ./lib/colours.sh",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "source ./lib/colours.sh",
+    "line_start": 8,
+    "line_end": 8,
+    "metadata": {
+      "module": "./lib/colours.sh",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "9265bcd393cdbfc7"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "import",
+    "name": ". /etc/greeter.conf",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": ". /etc/greeter.conf",
+    "line_start": 9,
+    "line_end": 9,
+    "metadata": {
+      "module": "/etc/greeter.conf",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "9e439113ee561e27"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "variable",
+    "name": "DEFAULT_GREETING",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "DEFAULT_GREETING=\"Hello\"",
+    "line_start": 11,
+    "line_end": 11,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "38cfd35861b45035"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "comment",
+    "name": "",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "# trailing comment: its own chunk",
+    "line_start": 11,
+    "line_end": 11,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "c8b87f6c0550268b"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "variable",
+    "name": "LOCALE",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "# Standalone note, separated by blank lines from any definition.\n# Second line of the same block.\nLOCALE=\"${LANG:-en}\"",
+    "line_start": 13,
+    "line_end": 15,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "d74e7f5621a74641"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "variable",
+    "name": "API_URL",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "export API_URL=\"https://example.com\"",
+    "line_start": 16,
+    "line_end": 16,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "1139af1e903fa001"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "variable",
+    "name": "MAX_RETRIES",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "readonly MAX_RETRIES=3",
+    "line_start": 17,
+    "line_end": 17,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "b892bc4e4a150620"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "variable",
+    "name": "COUNTER",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "declare -i COUNTER=0",
+    "line_start": 18,
+    "line_end": 18,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "2a9cfb0b1658749c"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "variable",
+    "name": "greet",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "alias greet=\"format_greeting\"",
+    "line_start": 19,
+    "line_end": 19,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "2b5409aa288fb92c"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "function",
+    "name": "format_greeting",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "# Format a greeting for a single recipient.\nformat_greeting() {\n    local name=\"$1\"\n    echo \"${DEFAULT_GREETING}, ${name} (${LOCALE})\"\n}",
+    "line_start": 21,
+    "line_end": 25,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "b57d1fd8270452eb"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "function",
+    "name": "greet_all",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "# Greet every argument in turn.\ngreet_all() {\n    for name in \"$@\"; do\n        format_greeting \"$name\"\n    done\n}",
+    "line_start": 27,
+    "line_end": 32,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "938eaca775c955f0"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "doc_section",
+    "name": "",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "greet_all \"$@\"",
+    "line_start": 34,
+    "line_end": 34,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "28fef2e3cc81696c"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "doc_section",
+    "name": "",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "mkdir -p \"${HOME}/.greeter\"",
+    "line_start": 36,
+    "line_end": 36,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "3b9dadb425a9561b"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "bash.sh",
+    "kind": "doc_section",
+    "name": "",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "if [ -z \"${GREETER_QUIET:-}\" ]; then\n  greet \"$DEFAULT_GREETING\"\nfi",
+    "line_start": 38,
+    "line_end": 40,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "1c837acadf784a90"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "lib/colours.sh",
+    "kind": "variable",
+    "name": "RED",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "#!/usr/bin/env bash\n# Terminal colour codes.\nRED='\\033[0;31m'",
+    "line_start": 1,
+    "line_end": 3,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "a0e8a338025ec509"
+  },
+  {
+    "blob_sha": "sha1",
+    "file_path": "lib/colours.sh",
+    "kind": "variable",
+    "name": "RESET",
+    "scope": "",
+    "language": "bash",
+    "file_language": "bash",
+    "content": "RESET='\\033[0m'",
+    "line_start": 4,
+    "line_end": 4,
+    "metadata": {
+      "module": "",
+      "names": "",
+      "dots": "",
+      "language_hint": ""
+    },
+    "id": "19e70f62367c0169"
+  }
+]

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/cases_docstrings.py

@@ -0,0 +1,112 @@
+"""Bash docstring-extraction test cases.
+
+tree-sitter-bash uses a single `comment` node for any `#` line. Function
+docs are a `#` comment run directly above the definition; a shebang
+(`#!/bin/bash`) attaches to the first function only when no blank line
+separates them.
+
+Each `@case` returns `(lang, source, symbol_name, snippet)`; see
+`test_docstrings.py` for the assertion direction per tag.
+"""
+
+from __future__ import annotations
+
+from pytest_cases import case
+
+type DocstringCase = tuple[str, str, str, str]
+
+
+@case(tags=["documented", "canonical", "exterior_doc"])
+def case_bash_hash_doc_on_function() -> DocstringCase:
+    """Canonical `#` comment above a shell function."""
+    src = """\
+# Greet the user.
+greet() {
+  echo hello
+}
+"""
+    return "bash", src, "greet", "Greet the user"
+
+
+@case(tags=["documented", "canonical", "exterior_doc"])
+def case_bash_multi_line_hash_doc() -> DocstringCase:
+    """Multi-line `#` comment run."""
+    src = """\
+# Greet the user.
+#
+# Reads the name from $1.
+greet() {
+  echo hi $1
+}
+"""
+    return "bash", src, "greet", "Reads the name from"
+
+
+@case(tags=["documented", "edge_case", "exterior_doc"])
+def case_bash_shebang_attached_to_first_function() -> DocstringCase:
+    """When a function follows the shebang with no blank line,
+    the shebang attaches — an honest consequence of the
+    flexible attachment policy.  Recording this as a case so
+    any future tightening does not regress silently.
+    """
+    src = """\
+#!/bin/bash
+# Entry point.
+main() {
+  echo hi
+}
+"""
+    return "bash", src, "main", "#!/bin/bash"
+
+
+@case(tags=["documented", "unconventional", "exterior_doc"])
+def case_bash_comment_with_script_style_heading() -> DocstringCase:
+    """Heading-like comment above a function attaches."""
+    src = """\
+# ==== helpers ====
+# Trim whitespace from $1.
+trim() {
+  echo "$1"
+}
+"""
+    return "bash", src, "trim", "Trim whitespace"
+
+
+@case(tags=["undocumented", "no_docs"])
+def case_bash_fn_without_doc() -> DocstringCase:
+    """Undocumented shell function."""
+    src = """\
+bare() {
+  echo hi
+}
+"""
+    return "bash", src, "bare", "PHANTOM_DOC_TEXT_SHOULD_NEVER_APPEAR"
+
+
+@case(tags=["undocumented", "boundary_not_attached"])
+def case_bash_doc_detached_by_blank_line() -> DocstringCase:
+    """Blank line breaks attachment."""
+    src = """\
+# Orphan.
+
+later() {
+  echo hi
+}
+"""
+    return "bash", src, "later", "Orphan"
+
+
+@case(tags=["undocumented", "invalid"])
+def case_bash_shebang_separated_by_blank_line() -> DocstringCase:
+    """When a blank line separates the shebang from the first
+    function, the shebang stays detached — the same
+    blank-line rule applies uniformly to all comment kinds.
+    """
+    src = """\
+#!/bin/bash
+
+main() {
+  echo hi
+}
+"""
+    return "bash", src, "main", "#!/bin/bash"

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/cases_extraction.py

@@ -0,0 +1,138 @@
+"""Bash extraction test cases.
+
+Each `@case` returns test data consumed by `test_extraction.py` via
+`pytest-cases`.
+"""
+
+from __future__ import annotations
+
+from pytest_cases import case
+
+type SymbolCase = tuple[str, str, list[tuple[str, str, str]]]
+type MixedCase = tuple[str, str, set[str], list[tuple[str, str]]]
+
+
+@case(tags=["symbol"])
+def case_bash_function_keyword() -> SymbolCase:
+    """function deploy { ... }."""
+    src = """\
+function deploy {
+    echo deploying
+}
+"""
+    return "bash", src, [("function", "deploy", "")]
+
+
+@case(tags=["symbol"])
+def case_bash_function_keyword_parens() -> SymbolCase:
+    """function deploy() { ... }."""
+    src = """\
+function deploy() {
+    echo deploying
+}
+"""
+    return "bash", src, [("function", "deploy", "")]
+
+
+@case(tags=["symbol"])
+def case_bash_function_posix() -> SymbolCase:
+    """deploy() { ... } — POSIX syntax."""
+    src = """\
+deploy() {
+    echo deploying
+}
+"""
+    return "bash", src, [("function", "deploy", "")]
+
+
+@case(tags=["symbol"])
+def case_bash_multiple_functions() -> SymbolCase:
+    """Multiple shell functions."""
+    src = """\
+function setup {
+    echo setup
+}
+
+function teardown {
+    echo teardown
+}
+
+run() {
+    echo run
+}
+"""
+    return (
+        "bash",
+        src,
+        [
+            ("function", "setup", ""),
+            ("function", "teardown", ""),
+            ("function", "run", ""),
+        ],
+    )
+
+
+@case(tags=["symbol"])
+def case_bash_alias() -> SymbolCase:
+    """An alias is a variable, named without the `=` the grammar fuses on."""
+    src = """\
+alias ll="ls -l"
+"""
+    return "bash", src, [("variable", "ll", "")]
+
+
+@case(tags=["symbol"])
+def case_bash_function_local_vars() -> SymbolCase:
+    """Function with local variables."""
+    src = """\
+setup() {
+    local dir="/tmp"
+    mkdir -p "$dir"
+}
+"""
+    return "bash", src, [("function", "setup", "")]
+
+
+@case(tags=["symbol"])
+def case_bash_function_conditionals() -> SymbolCase:
+    """Function with conditionals."""
+    src = """\
+check() {
+    if [ -f /tmp/x ]; then
+        echo yes
+    fi
+}
+"""
+    return "bash", src, [("function", "check", "")]
+
+
+# ── Mixed ───────────────────────────────────────────────────────────
+
+
+@case(tags=["symbol"])
+def case_bash_assignment() -> SymbolCase:
+    """Top-level variable assignment."""
+    return "bash", "MAX=100\n", [("variable", "MAX", "")]
+
+
+@case(tags=["mixed"])
+def case_bash_full_script() -> MixedCase:
+    """Realistic shell script with doc comments on every
+    function.  Expected-kinds tuple pins symbol extraction;
+    content invariants are in `test_docstrings.py`.
+    """
+    src = """\
+#!/bin/bash
+
+# Deploy the current build to the given environment.
+deploy() {
+    local env="$1"
+    echo "deploying to $env"
+}
+
+# Roll back the last deploy.
+rollback() {
+    echo "rolling back"
+}
+"""
+    return "bash", src, {"function"}, []

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/samples/bash/bash.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Greeter — print greetings for named recipients.
+#
+# Bash has no classes or methods; the plugin extracts functions,
+# top-level variable assignments (including export/declare/readonly),
+# aliases, and source/. imports.
+
+source ./lib/colours.sh
+. /etc/greeter.conf
+
+DEFAULT_GREETING="Hello" # trailing comment: its own chunk
+
+# Standalone note, separated by blank lines from any definition.
+# Second line of the same block.
+LOCALE="${LANG:-en}"
+export API_URL="https://example.com"
+readonly MAX_RETRIES=3
+declare -i COUNTER=0
+alias greet="format_greeting"
+
+# Format a greeting for a single recipient.
+format_greeting() {
+    local name="$1"
+    echo "${DEFAULT_GREETING}, ${name} (${LOCALE})"
+}
+
+# Greet every argument in turn.
+greet_all() {
+    for name in "$@"; do
+        format_greeting "$name"
+    done
+}
+
+greet_all "$@"
+
+mkdir -p "${HOME}/.greeter"
+
+if [ -z "${GREETER_QUIET:-}" ]; then
+  greet "$DEFAULT_GREETING"
+fi

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/samples/bash/lib/colours.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Terminal colour codes.
+RED='\033[0;31m'
+RESET='\033[0m'

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/test_docstrings.py

@@ -0,0 +1,50 @@
+"""Bash docstring-extraction tests.
+
+Bash docs are exterior (a leading `#` comment run); there are no
+interior-doc cases, so only the documented / undocumented / exterior-doc
+checks apply.
+"""
+
+from __future__ import annotations
+
+from pytest_cases import parametrize_with_cases
+
+from rbtr.git import FileEntry
+from rbtr.languages.extract import extract_file
+
+
+@parametrize_with_cases(
+    "lang, source, name, snippet", cases=".cases_docstrings", has_tag="documented"
+)
+def test_documented_chunk_includes_doc_text(
+    lang: str, source: str, name: str, snippet: str
+) -> None:
+    """By default the chunk content carries the symbol's docs."""
+    chunks = extract_file(FileEntry("input", "sha1", source.encode()), lang)
+    chunk = next(c for c in chunks if c.name == name)
+    assert snippet in chunk.content, (
+        f"expected {snippet!r} in {lang}.{name} content; got:\n{chunk.content!r}"
+    )
+
+
+@parametrize_with_cases(
+    "lang, source, name, snippet", cases=".cases_docstrings", has_tag="undocumented"
+)
+def test_no_phantom_documentation(lang: str, source: str, name: str, snippet: str) -> None:
+    """Symbols without documentation do not gain any in content."""
+    chunks = extract_file(FileEntry("input", "sha1", source.encode()), lang)
+    chunk = next(c for c in chunks if c.name == name)
+    assert snippet not in chunk.content, (
+        f"unexpected {snippet!r} in {lang}.{name} content; got:\n{chunk.content!r}"
+    )
+
+
+@parametrize_with_cases(
+    "lang, source, name, snippet", cases=".cases_docstrings", has_tag="exterior_doc"
+)
+def test_leading_doc_folds_into_symbol(lang: str, source: str, name: str, snippet: str) -> None:
+    """A leading comment block folds into its symbol's chunk content."""
+    chunk = next(
+        c for c in extract_file(FileEntry("input", "sha1", source.encode()), lang) if c.name == name
+    )
+    assert snippet in chunk.content

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/test_extraction.py

@@ -0,0 +1,80 @@
+"""Bash extraction tests.
+
+Construct/mixed cases (`cases_extraction.py`) drive the shared checks;
+the function at the end pins bash's source/. import behaviour.
+"""
+
+from __future__ import annotations
+
+from pytest_cases import parametrize_with_cases
+
+from rbtr.domain.models import ChunkKind
+from rbtr.git import FileEntry
+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}"
+
+
+@parametrize_with_cases(
+    "lang, source, expected_kinds, expected_methods", cases=".cases_extraction", has_tag="mixed"
+)
+def test_extracts_all_expected_kinds(
+    lang: str,
+    source: str,
+    expected_kinds: set[str],
+    expected_methods: list[tuple[str, str]],
+) -> None:
+    """Realistic source produces all expected chunk kinds and method scoping."""
+    chunks = extract_file(FileEntry("input", "sha1", source.encode()), lang)
+    kinds = {c.kind for c in chunks}
+    for kind in expected_kinds:
+        assert kind in kinds, f"expected kind {kind!r} not in {kinds}"
+    methods = [(c.name, c.scope) for c in chunks if c.kind == ChunkKind.METHOD]
+    for name, scope in expected_methods:
+        assert (name, scope) in methods, f"expected method ({name}, {scope}) not in {methods}"
+
+
+def test_bash_source_and_dot_extracted_as_imports() -> None:
+    """source/. commands are captured as imports."""
+    src = """\
+source ./env.sh
+. /etc/profile
+"""
+    chunks = extract_file(FileEntry("input", "sha1", src.encode()), "bash")
+    imports = [c for c in chunks if c.kind == ChunkKind.IMPORT]
+    assert len(imports) == 2
+    modules = {c.metadata.module for c in imports}
+    assert modules == {"./env.sh", "/etc/profile"}
+
+
+def test_bash_top_level_commands_are_searchable() -> None:
+    """A script's commands are what it does, so none is left out.
+
+    A deploy script may define nothing at all, and before this its every
+    command sat in no chunk.
+    """
+    src = """\
+set -euo pipefail
+
+DEST=/srv/app
+
+rsync -a ./build/ "$DEST"
+
+if [ -d "$DEST" ]; then
+  systemctl restart app
+fi
+"""
+    chunks = list(extract_file(FileEntry("deploy.sh", "sha1", src.encode()), "bash"))
+    covered = {line for c in chunks for line in range(c.line_start, c.line_end + 1)}
+    lines = src.splitlines()
+    uncovered = [
+        lines[i - 1] for i in range(1, len(lines) + 1) if i not in covered and lines[i - 1].strip()
+    ]
+    assert uncovered == []

rbtr_lang_bash-2026.9.0.dev1/src/rbtr_lang_bash/tests/test_samples.py

@@ -0,0 +1,82 @@
+"""Bash sample extraction: the `samples/bash/` project through the real pipeline.
+
+The snapshots are the golden record of what bash extraction produces;
+regenerate with `pytest --snapshot-update` after an intended change.
+Engine-wide invariants (determinism, line numbers, syntax-error recovery)
+are covered once in core, not re-run per language.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+from tree_sitter import Parser
+
+from rbtr.domain.models import Chunk, ChunkKind, Edge
+from rbtr.git import FileEntry
+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]]:
+    """The `(relative path, text)` files of the `samples/bash/` project."""
+    root = Path(__file__).parent / "samples" / "bash"
+    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]:
+    """Chunks from every project file, each via the real `extract_file`."""
+    manager = get_manager()
+    out: list[Chunk] = []
+    for path, text in project:
+        lang = manager.detect_language(path) or "bash"
+        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]:
+    """Import edges inferred across the project's files."""
+    manager = get_manager()
+    return infer_import_edges(chunks, {p for p, _ in project}, build_resolution_map(manager))
+
+
+def test_emits_expected_kinds(chunks: list[Chunk]) -> None:
+    """The sample exercises bash's function, variable, and import chunks."""
+    kinds = {c.kind for c in chunks}
+    assert {
+        ChunkKind.FUNCTION,
+        ChunkKind.VARIABLE,
+        ChunkKind.IMPORT,
+        ChunkKind.COMMENT,
+    } <= kinds
+
+
+def test_parses_cleanly(project: list[tuple[str, str]]) -> None:
+    """Every project file is valid source — no tree-sitter ERROR/MISSING nodes."""
+    manager = get_manager()
+    for path, text in project:
+        grammar = manager.grammar(manager.detect_language(path) or "bash")
+        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