Skip to content

feat: add optional language extras for tree-sitter grammar dependencies #5

@hey-granth

Description

@hey-granth

Summary

Currently pip install codectx installs tree-sitter grammars for all supported languages regardless of what the user actually needs. This issue tracks introducing optional extras so users install only the grammars relevant to their codebase.

Motivation

  • Users analyzing Python-only repos have no reason to install Go or Rust grammars
  • Fewer installed packages means faster dependency resolution and smaller conflict surface in user environments
  • Explicit extras (codectx[go]) communicate supported languages clearly at install time
  • Cleaner dependency graph for downstream tools that inspect transitive dependencies

Proposed Interface

pip install codectx              # core + Python grammar (default use case)
pip install codectx[go]          # core + Python + Go
pip install codectx[rust]        # core + Python + Rust
pip install codectx[go,rust]     # core + Python + Go + Rust
pip install codectx[all]         # core + all supported language grammars

Python grammar is bundled by default since the primary audience is Python developers and bare pip install codectx must work out of the box for the most common case.

pyproject.toml Changes

[project.dependencies]
tree-sitter-python = "*"   # always included

[project.optional-dependencies]
go = ["tree-sitter-go"]
rust = ["tree-sitter-rust"]
javascript = ["tree-sitter-javascript"]
typescript = ["tree-sitter-typescript"]
all = [
    "tree-sitter-go",
    "tree-sitter-rust",
    "tree-sitter-javascript",
    "tree-sitter-typescript",
]

Runtime Behavior

When a user runs codectx on a repository containing a language whose grammar
is not installed, codectx should fail with a clear, actionable error:

Language 'go' detected but tree-sitter-go is not installed.
Run: pip install codectx[go]

No silent fallback, no partial analysis without warning.

Implementation Notes

  • Update pyproject.toml with extras as above
  • Add grammar availability check at pipeline entry before walking starts
  • Raise a descriptive error with the correct install command when a
    required grammar is missing
  • Update CLI help text to mention extras
  • Update documentation to cover the new install variants
  • Update README.md install section

Acceptance Criteria

  • pip install codectx installs only core and Python grammar
  • Each language extra installs only its grammar
  • codectx[all] installs all grammars
  • Missing grammar produces a clear error with the correct install command
  • No behavior change for users who already have all grammars installed

Out of Scope

  • Adding support for new languages (separate issue)
  • Auto-detecting and prompting to install missing grammars interactively

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions