feat(languages): parse shell to AST (functions, source edges, complexity) (#768)

Promote shell from the config/data passthrough tier to a parsed language.
tree-sitter-bash now yields function symbols, `source` / `.` import edges,
command call edges, and function-level code-health complexity.

- specs/shell.py: grammar + scm + builtin call filter; drop passthrough
- queries/shell.scm: function_definition symbols, source/. imports, calls
- resolvers/shell.py: literal-relative paths, the $SCRIPT_DIR / dirname
  idioms, and a unique path-suffix match for project-root anchors
  (`$BATS_ROOT/$LIBDIR/lib/x.sh`); genuinely dynamic paths stay external
- complexity map: CCN / nesting with `&&` / `||` command lists counted
- dead code: never-flag *.sh / *.bash / *.zsh (invoked by name, not imported)

Smoke on bats-core (54 files): 100% parse rate, 151 function symbols,
statically-resolvable source edges resolve, external binaries mint no call
edges, and the gnarliest function (CCN 23) surfaces in health.

Author: RaghavChamadiya

README.md

@@ -363,7 +363,8 @@ Install from the Marketplace (search **Repowise**) or Open VSX, then run
 | **Full** | Python · TypeScript · JavaScript · Java · Kotlin · Go · Rust · C++ · C# · Scala · Ruby | AST parsing, import resolution, named bindings, call resolution, heritage extraction, docstrings; multi-project workspace resolvers; framework-aware edges; per-language dynamic-hint extractors; **code-health markers** |
 | **Good** | C · Swift · PHP · Dart | AST parsing, import resolution, named bindings, call resolution, heritage (mixins / derive / extensions / traits), docstrings; dedicated workspace-aware resolvers; Laravel / TYPO3 / Flutter framework edges; dynamic-hint extractors; Dart adds code-health + perf markers |
 | **SQL / dbt** | `.sql` via sqlglot (postgres, mysql, tsql, clickhouse, ...) | Tables / views / functions / procedures as symbols with wiki pages; dbt projects get real `ref()` / `source()` lineage edges: model-level DAG, hotspots, co-change, ownership |
-| **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · Terraform · Markdown · Shell | Included in the file tree; special handlers extract endpoints / targets where applicable |
+| **Shell** | `.sh` · `.bash` · `.zsh` | Functions as symbols, `source` / `.` import edges (`$SCRIPT_DIR` / `dirname` idioms), and function-level code-health complexity. No class metrics, heritage, or dead-code flagging |
+| **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · Terraform · Markdown | Included in the file tree; special handlers extract endpoints / targets where applicable |
 | **Git-blame only** | Objective-C · Elixir · Erlang · Zig · Julia · Clojure · Haskell · OCaml · F# · … | Tracked in git history (blame, hotspots, co-change); no AST parsing yet |
 
 Adding a language needs **one `.scm` query file and one config entry**, with no

docs/LANGUAGE_SUPPORT.md

@@ -1,6 +1,6 @@
 # Language Support
 
-repowise parses **15 languages to a full AST**, resolves imports and call
+repowise parses **16 languages to a full AST**, resolves imports and call
 graphs across them, and scores **11 at the Full tier** with code-health markers.
 Everything else in your repo is still tracked through git history and appears in
 the wiki. This page is the "what works for my language today" reference.
@@ -22,7 +22,8 @@ produce meaningful output.
 | **Full** | Python · TypeScript · JavaScript · Java · Kotlin · Go · Rust · C++ · C# · Scala · Ruby | AST parsing, import resolution, named bindings, call resolution, heritage, docstrings, framework-aware edges, dynamic-hint extractors, and **code-health markers** |
 | **Good** | C · Swift · PHP · Dart | Everything above except code-health markers (C, Swift, PHP; Dart *does* get health markers). Dedicated workspace resolvers and framework edges per language |
 | **SQL / dbt** | `.sql` via sqlglot | Tables / views / functions / procedures as symbols with wiki pages; dbt projects get real `ref()` / `source()` lineage |
-| **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · Terraform · Markdown · Shell | In the file tree and wiki; special handlers extract endpoints / targets where applicable |
+| **Shell** | `.sh` `.bash` `.zsh` | Function definitions as symbols, `source` / `.` import edges (incl. `$SCRIPT_DIR` / `dirname` / `$BATS_ROOT` idioms), and function-level code-health complexity (CCN, nesting, cognitive). No class metrics, heritage, bindings, or dead-code flagging |
+| **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · Terraform · Markdown | In the file tree and wiki; special handlers extract endpoints / targets where applicable |
 | **Lightweight** | Elixir · Clojure · Haskell · Lean 4 · Erlang · F# | Regex-tier file-level import graph (no symbols/calls). Honest file-to-file dependencies, no symbol-level claims |
 | **Partial** | Luau / Roblox | AST symbols + `require()` resolution (Rojo / `.luaurc` aware); no health markers yet |
 | **Structural** | Objective-C · R · Zig · Julia · Elm · OCaml · Crystal · Nim · D | Git history only (blame, hotspots, co-change). No AST parsing |
@@ -150,6 +151,20 @@ instance paths (including `:WaitForChild` idioms), absolute Roblox paths via
 Rojo's `default.project.json`, and `@alias` requires via `.luaurc`. No health
 markers yet.
 
+**Shell** (`.sh` / `.bash` / `.zsh`), function definitions (both `foo()` and
+`function foo` forms) become symbols, `source` / `.` statements become import
+edges, and calls to functions defined in the same or a sourced file resolve to
+call edges (external binaries like `grep` mint no edge). Import resolution
+covers literal relative paths plus the common directory-anchor idioms
+(`$SCRIPT_DIR/x.sh`, `$(dirname "$0")/x.sh`, `${BASH_SOURCE%/*}/x.sh`) and
+project-root anchors (`$BATS_ROOT/$LIBDIR/lib/x.sh`) via a unique path-suffix
+match; genuinely dynamic paths (`source "$1"`) stay external. Shell also gets
+**function-level complexity** markers (CCN / nesting / cognitive, with `&&` /
+`||` command lists counted). tree-sitter-bash parses the bash/POSIX subset, so
+zsh mostly works and fish does not; any parse error degrades that file to
+passthrough. No class metrics, heritage, bindings, or dead-code flagging (shell
+scripts are invoked by name, so static reachability is meaningless).
+
 **Structural** (Objective-C, R, Zig, Julia, Elm, OCaml, Crystal, Nim, D) -
 tracked in git history (blame, hotspots, co-change) but no AST parsing. Files
 appear in the wiki as traversal-level entries, and the knowledge graph runs in
@@ -178,6 +193,7 @@ is "Full" vs "Good".
 | Dart | ✅ | n/a³ | ✅ | later | ✅ |
 | Scala | ✅ | ✅ | ✅⁴ | later | ✅⁵ |
 | Ruby | ✅ | ✅⁶ | ✅⁷ | later | ✅⁸ |
+| Shell | ✅⁹ | n/a | n/a | n/a | n/a |
 
 ¹ Go methods attach to a type via an external receiver rather than nesting in a
 class body, so class-level metrics aren't computable; Go gets the function- and
@@ -216,6 +232,11 @@ keeps in-memory `Registry.find(name)` lookups silent. Backticks / `system` /
 `Open3` are subprocess sinks; `s += "…"` in a loop is flagged while `s << x`
 (amortized append) never is.
 
+⁹ Shell gets function-level complexity only (CCN / nesting / cognitive / NLOC).
+`&&` / `||` command lists count toward CCN (`cmd || exit 1` is +1), which is
+honest: shell branching is chained command lists. There are no classes,
+assertions, dataflow, or perf dialect for shell.
+
 The **performance** signal (`io_in_loop`, `string_concat_in_loop`,
 `resource_construction_in_loop`, language-specific markers like Go
 `defer_in_loop` and C# sync-over-async) and the **dataflow** layer (powering
@@ -237,6 +258,7 @@ where a dialect isn't wired yet. Per-marker mechanics and precision hazards:
 | Elixir | Good | Lightweight tier shipped; AST upgrade planned (`tree-sitter-elixir` available) |
 | F# | Good | Lightweight tier shipped; AST upgrade planned (`tree-sitter-f-sharp` available) |
 | SQL / dbt | - | DDL symbols, dbt lineage, app-to-database contracts, health markers shipped. Next: column-level blast radius |
+| Shell | - | Function symbols, `source` import edges, function-level complexity shipped. Next: shebang-based detection of extensionless executables (a traverser capability) |
 
 ---
 

packages/core/src/repowise/core/analysis/dead_code/constants.py

@@ -20,6 +20,13 @@
 
 # Patterns that should never be flagged as dead.
 _NEVER_FLAG_PATTERNS: tuple[str, ...] = (
+    # Shell scripts are invoked by name from CI configs, Makefiles, and humans
+    # — static reachability is meaningless, so they are never flagged as dead.
+    # (Shell parses to a real AST now, so it left the passthrough-derived
+    # ``_NON_CODE_LANGUAGES`` exemption below; these globs restore it.)
+    "*.sh",
+    "*.bash",
+    "*.zsh",
     "*__init__.py",
     "*__main__.py",
     "*conftest.py",

packages/core/src/repowise/core/analysis/health/complexity/languages.py

@@ -664,6 +664,34 @@ class LanguageNodeMap:
 )
 
 
+_SHELL = LanguageNodeMap(
+    # Both `foo() {}` and `function foo {}` parse as function_definition; its
+    # body is a sibling `compound_statement` the shared walker measures.
+    function_kinds=frozenset({"function_definition"}),
+    # Shell has no anonymous-function literal.
+    lambda_kinds=frozenset(),
+    # `elif` is its own clause (a branch); `else_clause` is not a decision.
+    branch_kinds=frozenset({"if_statement", "elif_clause"}),
+    # `until ...` parses as `while_statement` in tree-sitter-bash, so it is
+    # covered here; `for ((;;))` is `c_style_for_statement`.
+    loop_kinds=frozenset(
+        {"for_statement", "c_style_for_statement", "while_statement"}
+    ),
+    # No exceptions in shell (`trap` is not `try`).
+    try_kinds=frozenset(),
+    catch_kinds=frozenset(),
+    switch_kinds=frozenset({"case_statement"}),
+    case_kinds=frozenset({"case_item"}),
+    boolean_operator_kinds=frozenset(),
+    # `cmd && other` / `cmd || exit 1` parse as a `list` node carrying the
+    # operator as a direct `&&` / `||` token — the walker sniffs that token.
+    # This counts the guard idiom (`cmd || exit 1`) as +1 CCN, which is honest:
+    # shell branching IS chained command lists.
+    boolean_operator_text_kinds=frozenset({"list"}),
+    # No classes, no assertions, no perf/dataflow dialect for shell.
+)
+
+
 LANGUAGE_MAPS: dict[str, LanguageNodeMap] = {
     "python": _PY,
     "typescript": _TS,
@@ -679,6 +707,7 @@ class LanguageNodeMap:
     "dart": _DART,
     "scala": _SCALA,
     "ruby": _RUBY,
+    "shell": _SHELL,
 }
 
 

packages/core/src/repowise/core/ingestion/language_configs.py

@@ -355,4 +355,16 @@ class LanguageConfig:
         parent_extraction="none",
         parent_class_types=frozenset(),
     ),
+    "shell": LanguageConfig(
+        # Both `foo() {}` and `function foo {}` parse as function_definition.
+        # Shell has no classes, so no parent tracking.
+        symbol_node_types={
+            "function_definition": "function",
+        },
+        import_node_types=["command"],  # `source` / `.` — see queries/shell.scm
+        export_node_types=[],
+        visibility_fn=public_by_default,
+        parent_extraction="none",
+        parent_class_types=frozenset(),
+    ),
 }

packages/core/src/repowise/core/ingestion/languages/specs/shell.py

@@ -2,12 +2,71 @@
 
 from ..spec import LanguageSpec
 
+# Shell builtins and no-op keywords that show up as `command` invocations but
+# are never user-defined functions — suppressed as call targets so the graph
+# only records edges to real functions (defined here or in a sourced file).
+_SHELL_BUILTINS = frozenset(
+    {
+        ".",
+        ":",
+        "[",
+        "[[",
+        "alias",
+        "bg",
+        "break",
+        "builtin",
+        "cd",
+        "command",
+        "continue",
+        "declare",
+        "echo",
+        "eval",
+        "exec",
+        "exit",
+        "export",
+        "false",
+        "fg",
+        "getopts",
+        "hash",
+        "let",
+        "local",
+        "logout",
+        "printf",
+        "pushd",
+        "popd",
+        "pwd",
+        "read",
+        "readonly",
+        "return",
+        "set",
+        "shift",
+        "shopt",
+        "source",
+        "test",
+        "trap",
+        "true",
+        "type",
+        "typeset",
+        "ulimit",
+        "umask",
+        "unalias",
+        "unset",
+        "wait",
+    }
+)
+
 SPEC = LanguageSpec(
     tag="shell",
     display_name="Shell",
     extensions=frozenset({".sh", ".bash", ".zsh"}),
+    # Shell is code *and* infra: files still promote to CI/infra presentation
+    # by name/path (see registry.non_infra_code_extensions), but they now get a
+    # real AST (functions, source edges, function-level complexity).
     is_infra=True,
-    is_passthrough=True,
-    shebang_tokens=("bash", " sh"),
+    import_support="partial",
+    grammar_package="tree_sitter_bash",
+    scm_file="shell.scm",
+    shebang_tokens=("bash", " sh", "zsh"),
+    builtin_calls=_SHELL_BUILTINS,
     color_hex="#89E051",
 )

packages/core/src/repowise/core/ingestion/queries/shell.scm

@@ -0,0 +1,44 @@
+; =============================================================================
+; repowise — Shell (bash/sh/zsh) symbol, import, and call queries
+; tree-sitter-bash (install separately if needed)
+;
+; Scope is deliberately small: function definitions as symbols, `source` / `.`
+; as import edges, and command invocations as call targets. External binaries
+; (grep, awk, …) are captured as call targets too, but resolve to nothing when
+; no matching function symbol exists — the three-tier call resolver drops them.
+;
+; tree-sitter-bash represents both function forms with `function_definition`
+; carrying a `name:` field:
+;     foo() { ... }
+;     function foo { ... }
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols — function definitions (both `foo()` and `function foo` forms).
+; ---------------------------------------------------------------------------
+(function_definition
+  name: (word) @symbol.name
+) @symbol.def
+
+; ---------------------------------------------------------------------------
+; Imports — `source <file>` and `. <file>`.
+;
+; The argument is captured as raw text (a string, word, or concatenation); the
+; parser strips surrounding quotes before handing it to resolvers/shell.py,
+; which resolves the common `$SCRIPT_DIR/x.sh` / `$(dirname "$0")/x.sh` idioms
+; against the sourcing file's directory.
+; ---------------------------------------------------------------------------
+(command
+  name: (command_name) @_src_cmd
+  argument: (_) @import.module
+  (#match? @_src_cmd "^(source|\\.)$")
+) @import.statement
+
+; ---------------------------------------------------------------------------
+; Calls — every command invocation's name. Only resolves for calls to
+; functions defined in the same file or a sourced file; builtins are filtered
+; via `builtin_calls` on the spec, external binaries drop during resolution.
+; ---------------------------------------------------------------------------
+(command
+  name: (command_name) @call.target
+) @call.site

packages/core/src/repowise/core/ingestion/resolvers/__init__.py

@@ -24,6 +24,7 @@
 from .ruby import resolve_ruby_import
 from .rust import resolve_rust_import
 from .scala import resolve_scala_import
+from .shell import resolve_shell_import
 from .sql import resolve_dbt_import
 from .swift import resolve_swift_import
 from .typescript import resolve_ts_js_import
@@ -46,6 +47,8 @@
     "swift": resolve_swift_import,
     "scala": resolve_scala_import,
     "php": resolve_php_import,
+    # source ./lib.sh + the $SCRIPT_DIR/$(dirname "$0") idioms.
+    "shell": resolve_shell_import,
     # Lightweight regex-tier resolvers (import_support="partial")
     "elixir": resolve_elixir_import,
     "dart": resolve_dart_import,