Add maxResults parameter and return text results by default

.github/workflows/test.yml

@@ -0,0 +1,70 @@
+# https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
+name: Tests
+
+on:  # https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+  push:
+    branches:
+    - '**'
+    tags-ignore:  # don't build tags
+    - '**'
+    paths-ignore:
+    - '**/*.md'
+  pull_request:
+    paths-ignore:
+    - '**/*.md'
+  workflow_dispatch:
+    # https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+      fail-fast: false
+
+    steps:
+    - name: Git Checkout
+      uses: actions/checkout@v4  # https://github.com/actions/checkout
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Set up Python
+      run: uv python install
+
+    - name: Install ast-grep
+      run: |
+        npm install -g @ast-grep/cli
+        ast-grep --version
+
+    - name: Install dependencies
+      run: |
+        uv sync --all-extras --dev
+
+    - name: Lint with ruff
+      run: |
+        uv run ruff check .
+
+    - name: Format check with ruff
+      run: |
+        uv run ruff format --check .
+      continue-on-error: true  # TODO
+
+    - name: Type check with mypy
+      run: |
+        uv run mypy main.py
+
+    - name: Run unit tests
+      run: |
+        uv run pytest tests/test_unit.py -v --cov=main --cov-report=term-missing
+
+    - name: Run integration tests
+      run: |
+        uv run pytest tests/test_integration.py -v

.gitignore

@@ -6,5 +6,8 @@ dist/
 wheels/
 *.egg-info
 
+# MyPy. Ruff, PyTest cache folders
+.*_cache/
+
 # Virtual environments
 .venv

README.md

@@ -131,6 +131,24 @@ Test ast-grep YAML rules against code snippets before applying them to larger co
 ### 🎯 `find_code`
 Search codebases using simple ast-grep patterns for straightforward structural matches.
 
+**Parameters:**
+- `max_results`: Limit number of complete matches returned (default: unlimited)
+- `output_format`: Choose between `"text"` (default, ~75% fewer tokens) or `"json"` (full metadata)
+
+**Text Output Format:**
+```
+Found 2 matches:
+
+path/to/file.py:10-15
+def example_function():
+    # function body
+    return result
+
+path/to/file.py:20-22
+def another_function():
+    pass
+```
+
 **Use cases:**
 - Find function calls with specific patterns
 - Locate variable declarations
@@ -139,6 +157,10 @@ Search codebases using simple ast-grep patterns for straightforward structural m
 ### 🚀 `find_code_by_rule`
 Advanced codebase search using complex YAML rules that can express sophisticated matching criteria.
 
+**Parameters:**
+- `max_results`: Limit number of complete matches returned (default: unlimited)
+- `output_format`: Choose between `"text"` (default, ~75% fewer tokens) or `"json"` (full metadata)
+
 **Use cases:**
 - Find nested code structures
 - Search with relational constraints (inside, has, precedes, follows)