Skip to content

feat(analyse): add Bash language support#92

Draft
ubmarco wants to merge 3 commits into
mainfrom
feat/bash-support-48
Draft

feat(analyse): add Bash language support#92
ubmarco wants to merge 3 commits into
mainfrom
feat/bash-support-48

Conversation

@ubmarco

@ubmarco ubmarco commented Jul 10, 2026

Copy link
Copy Markdown
Member

Adds bash as a supported comment_type for marker extraction. Closes #48.

What

  • New CommentType.bash, discovering .sh, .bash, .zsh and .ksh files.
  • Bash has only # line comments, so extraction reuses the existing hash-comment path: a (comment) @comment tree-sitter query over the tree-sitter-bash grammar, with function_definition scope nodes.
  • Adds the tree-sitter-bash>=0.25.1 dependency.

Tests & docs

  • A default_oneliner_bash case in the shared oneline.yaml extraction fixture, with its captured snapshot.
  • Discovery coverage for the new extensions; the comment-type enum error-message tests updated.
  • Documented as a new FE_BASH feature, with the configuration / analyse / changelog pages updated.

Not included

Fish shell — it is not POSIX-compatible and no tree-sitter-fish grammar is published on PyPI, so it cannot be wired into this package. Can be revisited if a PyPI grammar becomes available.

Add `bash` as a supported comment-type for marker extraction, discovering
`.sh`, `.bash`, `.zsh` and `.ksh` files. Bash has only `#` line comments,
so it reuses the existing hash-comment extraction path (BASH_QUERY +
`function_definition` scope nodes) via a tree-sitter-bash grammar.

A `default_oneliner_bash` case is added to the shared `oneline.yaml`
extraction fixture with its captured snapshot, and the feature is
documented under `FE_BASH`.

Fish shell is intentionally excluded: no tree-sitter-fish grammar is
published on PyPI, so it cannot be wired into this Python package.

Closes #48
@ubmarco

ubmarco commented Jul 11, 2026

Copy link
Copy Markdown
Member Author

Review

Must fix — the supported-styles table in configuration.rst is corrupted. The new Bash row was inserted mid-cell into the JSONC row: the continuation line (e.g. the mode line // -*- mode: jsonc -*-) now renders inside the Bash row's "discovered file types" cell, and the JSONC cell loses its example. Move the Bash row below that line. The RST stays syntactically valid, so the docs build can't catch this — worth an eyeball of the rendered table.

Test coverage

  • features.rst:255 guarantees that shebang lines never produce spurious markers, but nothing asserts it. Cheapest cover: a second bash case in the declarative oneline.yaml fixture whose source starts with #!/bin/bash. The function name { } definition form is likewise unexercised (the fixture uses greet() { … }).
  • FE_BASH lists "association of comments with function definitions" as a key capability, backed by SCOPE_NODE_TYPES:48; the fixture executes that path but nothing asserts the resulting scope.

Otherwise clean. Wiring is complete and consistent: enum + file-type map, query + init_tree_sitter branch, both hard-coded comment_type error-message tests updated, discovery test covers all four extensions, docs and changelog updated. The change is additive — the only user-visible behavior change besides the feature is the schema-validation error string now listing bash. CI is green across the matrix; no earlier review comments to address.

ubmarco added 2 commits July 11, 2026 23:06
… row

The bash row was inserted between the JSONC row's last cell and its
continuation line, so the mode-line example rendered inside the bash
"discovered file types" cell and the JSONC cell lost it.
…ssociation

- shebang_oneliner_bash extraction fixture: the shebang comment yields no
  marker or warning, the marker anchors to line 2, and `function name { }`
  definitions parse
- test_find_associated_scope_bash: comments associate with the
  function_definition for both definition syntaxes, including the
  enclosing-scope fallback for comments inside a body
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.45455% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.46%. Comparing base (43927d0) to head (fe82065).

Files with missing lines Patch % Lines
src/sphinx_codelinks/analyse/utils.py 80.00% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main      #92      +/-   ##
==========================================
+ Coverage   91.40%   91.46%   +0.06%     
==========================================
  Files          34       34              
  Lines        3012     3034      +22     
  Branches      322      323       +1     
==========================================
+ Hits         2753     2775      +22     
  Misses        160      160              
  Partials       99       99              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ubmarco

ubmarco commented Jul 11, 2026

Copy link
Copy Markdown
Member Author

Review findings addressed in f604413 and fe82065:

  1. Table fixed (f604413) — the JSONC example continuation line is back in the JSONC row's cell, and the Bash row now follows it cleanly: configuration.rst:325-332.
  2. Shebang and function keyword form covered (fe82065) — new declarative case shebang_oneliner_bash with its captured snapshot: the shebang comment yields no marker and no warning, the need anchors to line 2, and function greet { echo hi; } parses.
  3. Scope association asserted (fe82065) — new test_find_associated_scope_bash following the existing per-language pattern: comments associate with the function_definition for both definition syntaxes, plus the enclosing-scope fallback for a comment inside a function body.

Verified with the full tox suite (267 passed, 34 snapshots), mypy, and the pinned pre-commit hooks on the changed files; CI is green on fe82065.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bash Support

2 participants