context-grep

context-grep is a command-line tool that searches for regular expressions and extracts the surrounding code context using Neovim's Treesitter integration.

Usage

nix run github:ck3d/context-grep -- <pattern> <file>...

The <pattern> is parsed as a regular expression. It supports standard PCRE-like syntax.

Output Format

By default, context-grep outputs a human-readable, colorized, and structured representation of the matches. For example, running against test-harness/sample-data/sample.md with colors and icons disabled:

context-grep --color never --no-icons "TODO" test-harness/sample-data/sample.md

test-harness/sample-data/sample.md:7 markdown
  1│  # Sample doc
   ┆
  6│  def process(data):
  7│      # TODO: handle empty input
  7│  # TODO: handle empty input
  8│  return data

JSON Output Format

Alternatively, you can output a JSON array of match objects using the --format json flag. For example:

context-grep --format json "TODO" test-harness/sample-data/sample.md

[
  {
    "file": "test-harness/sample-data/sample.md",
    "match": {
      "text": "# TODO: handle empty input",
      "line": 7,
      "type": "comment",
      "language": "python"
    },
    "target": {
      "text": "return data",
      "line": 8,
      "type": "block",
      "language": "python"
    },
    "context": [
      {
        "text": "# Sample doc",
        "line": 1,
        "type": "section",
        "language": "markdown"
      },
      {
        "text": "def process(data):\n    # TODO: handle empty input",
        "line": 6,
        "type": "function_definition",
        "language": "python"
      }
    ],
    "filetype": "markdown"
  }
]

Each object has the following fields:

Field	Description
file	The file the match was found in.
filetype	The detected filetype
match	The matched node (the enclosing comment when the hit is inside a comment).
target	The nearest non-comment code sibling the comment refers to. Absent when none.
context	The enclosing structural scopes, ordered outermost → innermost. May be empty.

Each match, target, and context entry (when present) carries the node's text, its 1-based start line, its Treesitter type, and the language it was parsed as.

Supported Languages

context-grep supports any language for which an nvim-treesitter-context query is available. The Nix package pre-configures support for many supported languages.

Injected Languages

context-grep resolves matches against injected languages. A match inside an injected region is understood in that injected language, and the context may span multiple languages.

Development

Use the dev-check.sh for iterative per package development and nix flake check for a full repository check.