codemap-bash 0.1.0__tar.gz

codemap_bash-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.mypy_cache/
+.ruff_cache/
+.benchmarks/
+
+# Virtualenv
+.venv/
+venv/
+env/
+
+# uv / pdm lockfiles (commit uv.lock once we settle)
+# uv.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# CodeMap own index when dogfooding
+.codemap/

codemap_bash-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: codemap-bash
+Version: 0.1.0
+Summary: Bash / shell-script indexer plugin for CodeMap
+Project-URL: Homepage, https://github.com/qxbyte/codemap
+Author: CodeMap Contributors
+License: MIT
+Keywords: bash,codemap,indexer,shell,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Unix Shell
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.11
+Requires-Dist: codemap-core<0.2,>=0.1.0
+Requires-Dist: tree-sitter-bash>=0.25
+Requires-Dist: tree-sitter>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# codemap-bash
+
+> A Bash / shell-script indexer for [CodeMap](https://github.com/qxbyte/codemap),
+> shipped as an independent PyPI package.
+
+## What it captures
+
+Backed by `tree-sitter-bash`:
+
+| AST node | Symbol kind |
+|---|---|
+| `function_definition` | `function` |
+| Top-level `variable_assignment` | `variable` |
+| `declaration_command` (`readonly`/`declare`/`export`/`local`) at top level | `variable` (with `extra.bash_kind=<keyword>`) |
+
+Function bodies are **not** walked for inner assignments — anything
+declared inside a function is local state, not a script-level symbol.
+
+## Install
+
+```bash
+pip install codemap-bash
+```
+
+## SymbolID encoding
+
+```
+scip-bash . . . scripts/deploy.sh/greet().
+scip-bash . . . scripts/deploy.sh/MAX_RETRIES.
+```
+
+## File patterns
+
+* `*.sh`, `*.bash`, `*.bats`
+* Files without an extension whose shebang starts with `#!/bin/bash` or
+  `#!/usr/bin/env bash` are matched via `supports()`.
+
+## Limits
+
+* `source` / `.` includes are not turned into edges.
+* Aliases (`alias ll='ls -la'`) are not captured.
+* `getopts` argument schemas aren't structured.
+* POSIX sh / Zsh / Fish dialects parse, but constructs unique to them
+  may degrade to syntax-error diagnostics.
+
+## License
+
+MIT.

codemap_bash-0.1.0/README.md

@@ -0,0 +1,48 @@
+# codemap-bash
+
+> A Bash / shell-script indexer for [CodeMap](https://github.com/qxbyte/codemap),
+> shipped as an independent PyPI package.
+
+## What it captures
+
+Backed by `tree-sitter-bash`:
+
+| AST node | Symbol kind |
+|---|---|
+| `function_definition` | `function` |
+| Top-level `variable_assignment` | `variable` |
+| `declaration_command` (`readonly`/`declare`/`export`/`local`) at top level | `variable` (with `extra.bash_kind=<keyword>`) |
+
+Function bodies are **not** walked for inner assignments — anything
+declared inside a function is local state, not a script-level symbol.
+
+## Install
+
+```bash
+pip install codemap-bash
+```
+
+## SymbolID encoding
+
+```
+scip-bash . . . scripts/deploy.sh/greet().
+scip-bash . . . scripts/deploy.sh/MAX_RETRIES.
+```
+
+## File patterns
+
+* `*.sh`, `*.bash`, `*.bats`
+* Files without an extension whose shebang starts with `#!/bin/bash` or
+  `#!/usr/bin/env bash` are matched via `supports()`.
+
+## Limits
+
+* `source` / `.` includes are not turned into edges.
+* Aliases (`alias ll='ls -la'`) are not captured.
+* `getopts` argument schemas aren't structured.
+* POSIX sh / Zsh / Fish dialects parse, but constructs unique to them
+  may degrade to syntax-error diagnostics.
+
+## License
+
+MIT.

codemap_bash-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codemap-bash"
+version = "0.1.0"
+description = "Bash / shell-script indexer plugin for CodeMap"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "CodeMap Contributors" }]
+keywords = ["codemap", "bash", "shell", "indexer", "tree-sitter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Unix Shell",
+    "Topic :: Software Development",
+    "Topic :: System :: Shells",
+]
+dependencies = [
+    "codemap-core>=0.1.0,<0.2",
+    "tree-sitter>=0.25",
+    "tree-sitter-bash>=0.25",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.entry-points."codemap.indexers"]
+bash = "codemap_bash:BashIndexer"
+
+[project.urls]
+Homepage = "https://github.com/qxbyte/codemap"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codemap_bash"]

codemap_bash-0.1.0/src/codemap_bash/__init__.py

@@ -0,0 +1,8 @@
+"""Bash indexer plugin for CodeMap."""
+
+from __future__ import annotations
+
+from codemap_bash.indexer import BashIndexer
+
+__all__ = ["BashIndexer"]
+__version__ = "0.1.0"

codemap_bash-0.1.0/src/codemap_bash/indexer.py

@@ -0,0 +1,218 @@
+"""Bash indexer built on tree-sitter-bash.
+
+Only script-level symbols are emitted: function definitions, top-level
+variable assignments, and top-level ``readonly`` / ``declare`` /
+``export`` / ``local`` declaration commands. Variables defined inside a
+function body are intentionally not surfaced — they are private state,
+not a stable interface.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+from typing import ClassVar
+
+import tree_sitter
+import tree_sitter_bash
+
+from codemap.core.models import Diagnostic, Edge, IndexResult, Range, Symbol
+from codemap.core.symbol import Descriptor, DescriptorKind, SymbolID
+from codemap.indexers.base import IndexContext
+
+SCHEME = "scip-bash"
+LANG = "bash"
+
+_BASH_LANG = tree_sitter.Language(tree_sitter_bash.language())
+_DECLARATION_KEYWORDS = frozenset({"readonly", "declare", "export", "local", "typeset"})
+
+
+class BashIndexer:
+    name: ClassVar[str] = "bash"
+    version: ClassVar[str] = "0.1.0"
+    file_patterns: ClassVar[list[str]] = ["*.sh", "*.bash", "*.bats"]
+    languages: ClassVar[list[str]] = [LANG]
+
+    def supports(self, path: Path) -> bool:
+        if path.suffix in {".sh", ".bash", ".bats"}:
+            return True
+        # Extensionless files with a bash shebang are also accepted.
+        if path.suffix == "" and path.is_file():
+            try:
+                with path.open("rb") as f:
+                    head = f.read(64)
+                return _looks_like_bash_shebang(head)
+            except OSError:
+                return False
+        return False
+
+    def index_file(
+        self,
+        path: Path,
+        source: bytes,
+        ctx: IndexContext,
+    ) -> IndexResult:
+        try:
+            source.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            return IndexResult(
+                diagnostics=[
+                    Diagnostic(
+                        severity="error",
+                        file=ctx.relative_path,
+                        code="SH002",
+                        message=f"not valid UTF-8: {exc}",
+                        producer=self.name,
+                    )
+                ]
+            )
+        parser = tree_sitter.Parser(_BASH_LANG)
+        tree = parser.parse(source)
+        visitor = _Visitor(ctx.relative_path)
+        visitor.visit_root(tree.root_node)
+        diagnostics = list(visitor.diagnostics)
+        if tree.root_node.has_error:
+            diagnostics.append(
+                Diagnostic(
+                    severity="warning",
+                    file=ctx.relative_path,
+                    range=Range(start_line=1, end_line=1),
+                    code="SH001",
+                    message="tree-sitter reported parse errors; symbols may be incomplete",
+                    producer=self.name,
+                )
+            )
+        return IndexResult(
+            symbols=visitor.symbols,
+            edges=visitor.edges,
+            diagnostics=diagnostics,
+        )
+
+
+class _Visitor:
+    def __init__(self, relative_path: PurePosixPath) -> None:
+        self.relative_path = relative_path
+        self.symbols: list[Symbol] = []
+        self.edges: list[Edge] = []
+        self.diagnostics: list[Diagnostic] = []
+
+    def visit_root(self, root: tree_sitter.Node) -> None:
+        # We only walk the top-level statement list — function bodies are
+        # opaque from the symbol-table perspective.
+        for child in root.children:
+            self._visit_top_level(child)
+
+    def _visit_top_level(self, node: tree_sitter.Node) -> None:
+        kind = node.type
+        if kind == "function_definition":
+            self._emit_function(node)
+            return
+        if kind == "variable_assignment":
+            self._emit_variable(node, bash_kind=None)
+            return
+        if kind == "declaration_command":
+            self._emit_declaration(node)
+
+    def _emit_function(self, node: tree_sitter.Node) -> None:
+        name = _function_name(node)
+        if name is None:
+            return
+        sid = self._make_id(name, kind=DescriptorKind.METHOD)
+        self.symbols.append(
+            Symbol(
+                id=sid,
+                kind="function",
+                language=LANG,
+                file=self.relative_path,
+                range=_node_range(node),
+                signature=f"{name}()",
+            )
+        )
+
+    def _emit_variable(
+        self,
+        node: tree_sitter.Node,
+        *,
+        bash_kind: str | None,
+    ) -> None:
+        name = _variable_name(node)
+        if name is None:
+            return
+        sid = self._make_id(name, kind=DescriptorKind.TERM)
+        extra: dict[str, str] = {}
+        if bash_kind is not None:
+            extra["bash_kind"] = bash_kind
+        self.symbols.append(
+            Symbol(
+                id=sid,
+                kind="variable",
+                language=LANG,
+                file=self.relative_path,
+                range=_node_range(node),
+                extra=extra,
+            )
+        )
+
+    def _emit_declaration(self, node: tree_sitter.Node) -> None:
+        keyword: str | None = None
+        for child in node.children:
+            if child.type in _DECLARATION_KEYWORDS:
+                keyword = child.type
+                break
+        for child in node.children:
+            if child.type == "variable_assignment":
+                self._emit_variable(child, bash_kind=keyword)
+
+    def _make_id(self, name: str, *, kind: DescriptorKind) -> SymbolID:
+        descriptors = list(_path_namespaces(self.relative_path))
+        descriptors.append(Descriptor(name=name, kind=kind))
+        return SymbolID(scheme=SCHEME, descriptors=tuple(descriptors))
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers
+# ---------------------------------------------------------------------------
+
+
+def _path_namespaces(path: PurePosixPath) -> list[Descriptor]:
+    return [Descriptor(name=part, kind=DescriptorKind.NAMESPACE) for part in path.parts]
+
+
+def _node_range(node: tree_sitter.Node) -> Range:
+    sr, sc = node.start_point
+    er, ec = node.end_point
+    return Range(
+        start_line=sr + 1,
+        start_col=sc,
+        end_line=max(er + 1, sr + 1),
+        end_col=ec,
+    )
+
+
+def _node_text(node: tree_sitter.Node) -> str:
+    return node.text.decode("utf-8") if node.text is not None else ""
+
+
+def _function_name(node: tree_sitter.Node) -> str | None:
+    """``function greet() { ... }`` and ``helper() { ... }`` both expose the
+    function name as a ``word`` child (sitting either after the optional
+    ``function`` keyword or as the first content child).
+    """
+    for child in node.children:
+        if child.type == "word":
+            return _node_text(child)
+    return None
+
+
+def _variable_name(node: tree_sitter.Node) -> str | None:
+    """For ``variable_assignment``: the ``variable_name`` child."""
+    for child in node.children:
+        if child.type == "variable_name":
+            return _node_text(child)
+    return None
+
+
+_BASH_SHEBANGS = (b"#!/bin/bash", b"#!/usr/bin/env bash", b"#!/bin/sh", b"#!/usr/bin/env sh")
+
+
+def _looks_like_bash_shebang(head: bytes) -> bool:
+    return any(head.startswith(sb) for sb in _BASH_SHEBANGS)

codemap_bash-0.1.0/tests/test_indexer.py

@@ -0,0 +1,168 @@
+"""Unit tests for the Bash indexer plugin."""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path, PurePosixPath
+
+from codemap_bash import BashIndexer
+from codemap_bash.indexer import SCHEME
+
+from codemap.core.models import IndexResult
+from codemap.indexers.base import IndexContext
+
+
+def _index(source: str, *, path: str = "scripts/deploy.sh") -> IndexResult:
+    code = textwrap.dedent(source).lstrip("\n")
+    return BashIndexer().index_file(
+        Path(path),
+        code.encode("utf-8"),
+        IndexContext(
+            project_root=Path("/tmp/proj"),
+            relative_path=PurePosixPath(path),
+            language="bash",
+        ),
+    )
+
+
+def test_indexer_metadata() -> None:
+    ix = BashIndexer()
+    assert ix.name == "bash"
+    assert ix.languages == ["bash"]
+    assert ix.supports(Path("a.sh"))
+    assert ix.supports(Path("a.bash"))
+    assert ix.supports(Path("a.bats"))
+    assert not ix.supports(Path("a.py"))
+
+
+def test_scheme_is_consistent() -> None:
+    r = _index(
+        """
+        FOO=1
+        function f() { echo hi; }
+        """
+    )
+    for s in r.symbols:
+        assert str(s.id).startswith(f"{SCHEME} ")
+
+
+def test_function_definition_with_function_keyword() -> None:
+    r = _index(
+        """
+        function greet() {
+            echo "hi $1"
+        }
+        """
+    )
+    funcs = [s for s in r.symbols if s.kind == "function"]
+    assert len(funcs) == 1
+    assert "greet()." in str(funcs[0].id)
+
+
+def test_function_definition_without_keyword() -> None:
+    r = _index(
+        """
+        helper() {
+            local x=$1
+            return 0
+        }
+        """
+    )
+    funcs = [s for s in r.symbols if s.kind == "function"]
+    assert len(funcs) == 1
+    assert "helper()." in str(funcs[0].id)
+
+
+def test_top_level_variable_assignment() -> None:
+    r = _index("COUNT=10")
+    vars_ = [s for s in r.symbols if s.kind == "variable"]
+    assert len(vars_) == 1
+    assert "COUNT." in str(vars_[0].id)
+
+
+def test_readonly_declaration_tagged() -> None:
+    r = _index("readonly MAX_RETRIES=3")
+    vars_ = [s for s in r.symbols if s.kind == "variable"]
+    assert len(vars_) == 1
+    assert vars_[0].extra.get("bash_kind") == "readonly"
+
+
+def test_export_declaration_tagged() -> None:
+    r = _index('export PATH_VAR="/usr/local/bin"')
+    vars_ = [s for s in r.symbols if s.kind == "variable"]
+    assert vars_[0].extra.get("bash_kind") == "export"
+
+
+def test_declare_declaration_tagged() -> None:
+    r = _index("declare -i COUNTER=0")
+    vars_ = [s for s in r.symbols if s.kind == "variable"]
+    assert vars_[0].extra.get("bash_kind") == "declare"
+
+
+def test_function_internals_not_indexed() -> None:
+    """Variables declared inside a function body are local state, not
+    script-level symbols."""
+    r = _index(
+        """
+        helper() {
+            INNER_VAR=42
+            local INNER_LOCAL=7
+        }
+        """
+    )
+    vars_ = [s for s in r.symbols if s.kind == "variable"]
+    assert vars_ == []
+
+
+def test_multiple_top_level_symbols() -> None:
+    r = _index(
+        """
+        FOO=1
+        readonly BAR=2
+        function f() { echo hi; }
+        g() { :; }
+        """
+    )
+    funcs = [s for s in r.symbols if s.kind == "function"]
+    vars_ = [s for s in r.symbols if s.kind == "variable"]
+    assert {s.id.descriptors[-1].name for s in funcs} == {"f", "g"}
+    assert {s.id.descriptors[-1].name for s in vars_} == {"FOO", "BAR"}
+
+
+def test_symbol_id_uses_path_namespaces() -> None:
+    r = _index("FOO=1", path="scripts/utils/setup.sh")
+    var = next(s for s in r.symbols if s.kind == "variable")
+    assert str(var.id) == "scip-bash . . . scripts/utils/setup.sh/FOO."
+
+
+def test_empty_file_yields_no_symbols() -> None:
+    r = _index("")
+    assert r.symbols == []
+
+
+def test_invalid_utf8_yields_diagnostic() -> None:
+    ix = BashIndexer()
+    r = ix.index_file(
+        Path("bad.sh"),
+        b"\xff\xfe echo",
+        IndexContext(
+            project_root=Path("/tmp/proj"),
+            relative_path=PurePosixPath("bad.sh"),
+            language="bash",
+        ),
+    )
+    assert r.symbols == []
+    assert r.diagnostics[0].code == "SH002"
+
+
+def test_command_invocations_ignored() -> None:
+    """Commands like `cp foo bar` are not symbols."""
+    r = _index(
+        """
+        FOO=1
+        cp source dest
+        echo done
+        """
+    )
+    # Only FOO should appear; commands aren't symbols.
+    assert {s.id.descriptors[-1].name for s in r.symbols if s.kind == "variable"} == {"FOO"}