Merge pull request #132 from FluxxField/dev

feat: patterns collector and filetype dispatch middleware

Author: FluxxField

README.md

@@ -354,6 +354,8 @@ Here's a taste of what you can change with a single override:
 | Delete without moving cursor        | action        | `action = "remote_delete"`                   |
 | Make any motion cross-window        | metadata      | `multi_window = true`                        |
 | Auto-jump to closest target         | filter        | `filter = "first_target"`                    |
+| Match by vim regex instead of TS    | collector     | `collector = "patterns"`, `patterns = { "\\v\\f+" }` |
+| Adapt per filetype                  | metadata      | `filetype_overrides = { gitcommit = { ... } }` |
 | Customize labels for a motion       | keys          | `keys = "fdsarewq"`                          |
 | Exclude keys from labels            | exclude_keys  | `exclude_keys = "jk"`                        |
 

docs/Advanced-Recipes.md

@@ -429,6 +429,150 @@ action = merge({ "jump", "yank", "center" })
 
 ---
 
+## Filetype-Aware Motions
+
+The `filetype_overrides` system lets a single motion adapt its pipeline per filetype. Combined with the `patterns` collector, you can target structured text in any buffer — even without a treesitter parser.
+
+### Remote Yank Across Filetypes
+
+One keymap that yanks the "interesting thing" in any buffer:
+
+```lua
+require("smart-motion").register_motion("ry", {
+  collector = "treesitter",
+  extractor = "pass_through",
+  filter = "filter_visible",
+  visualizer = "hint_before",
+  modifier = "weight_distance",
+  action = "remote_yank",
+  map = true,
+  trigger_key = "ry",
+  modes = { "n" },
+  metadata = {
+    label = "Remote Yank",
+    motion_state = {
+      ts_node_types = { "identifier", "string_content", "constant" },
+      multi_window = true,
+      filetype_overrides = {
+        gitcommit = {
+          collector = "patterns",
+          motion_state = {
+            patterns = {
+              "\\vmodified:\\s+\\zs\\S.*$",
+              "\\vnew file:\\s+\\zs\\S.*$",
+              "\\vdeleted:\\s+\\zs\\S.*$",
+            },
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+**How it works:** In code files, this yanks treesitter identifiers and strings remotely (without moving the cursor). In a fugitive `gitcommit` buffer, it switches to the `patterns` collector and targets modified file paths instead. One keymap, two completely different data sources, same action.
+
+### Jump to Log File Entries
+
+```lua
+require("smart-motion").register_motion("<leader>l", {
+  collector = "treesitter",
+  extractor = "pass_through",
+  filter = "filter_visible",
+  visualizer = "hint_start",
+  action = "jump_centered",
+  map = true,
+  modes = { "n" },
+  metadata = {
+    motion_state = {
+      ts_node_types = { "function_declaration", "function_definition" },
+      filetype_overrides = {
+        log = {
+          collector = "patterns",
+          motion_state = {
+            patterns = {
+              "\\v(ERROR|WARN|FATAL)",
+              "\\v\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}",
+            },
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+**How it works:** In code, this jumps to functions. In `.log` files, it jumps to error keywords and ISO timestamps. The `patterns` collector handles the regex matching; the rest of the pipeline (filter, visualizer, action) stays the same.
+
+### Per-Language Treesitter Customization
+
+You don't need the `patterns` collector to use filetype overrides. You can swap treesitter config per language:
+
+```lua
+require("smart-motion").register_motion("]]", {
+  collector = "treesitter",
+  extractor = "pass_through",
+  filter = "filter_visible",
+  visualizer = "hint_start",
+  action = "jump_centered",
+  map = true,
+  modes = { "n", "o" },
+  metadata = {
+    motion_state = {
+      ts_node_types = { "function_declaration", "function_definition" },
+      filetype_overrides = {
+        python = {
+          motion_state = {
+            ts_node_types = { "function_definition", "class_definition", "decorated_definition" },
+          },
+        },
+        go = {
+          motion_state = {
+            ts_node_types = { "function_declaration", "method_declaration", "type_declaration" },
+          },
+        },
+        sql = {
+          motion_state = {
+            ts_query = [[
+              (function_definition fnc_name: (identifier) @fn)
+              (select_list_element (identifier) @alias)
+            ]],
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+**How it works:** Same treesitter collector everywhere, but each language gets the node types that make sense for it. Python includes `class_definition` and `decorated_definition`. Go includes `type_declaration`. SQL uses a raw query instead of node types. Languages without an override use the default `ts_node_types`.
+
+### Standalone Patterns Motion
+
+The `patterns` collector works independently — no filetype dispatch needed:
+
+```lua
+-- Jump to URLs anywhere in the buffer
+require("smart-motion").register_motion("<leader>u", {
+  collector = "patterns",
+  extractor = "pass_through",
+  filter = "filter_visible",
+  visualizer = "hint_start",
+  action = "jump",
+  map = true,
+  modes = { "n" },
+  metadata = {
+    motion_state = {
+      patterns = { "\\vhttps?://\\S+" },
+    },
+  },
+})
+```
+
+**How it works:** The `patterns` collector matches `https://...` URLs across visible buffer lines. No treesitter, no filetype dispatch — just a regex collector with standard pipeline stages.
+
+---
+
 ## Next Steps
 
 -> **[Recipes](Recipes.md)**: Pipeline basics, filter swaps, and preset overrides

docs/Building-Custom-Motions.md

@@ -58,6 +58,7 @@ Each stage is optional (except collector, extractor, visualizer, action). Each s
 |-----------|------------------|
 | `lines` | All lines in the buffer |
 | `treesitter` | Treesitter syntax nodes |
+| `patterns` | Vim regex matches against buffer lines |
 | `diagnostics` | LSP diagnostics |
 | `git_hunks` | Git changed regions |
 | `quickfix` | Quickfix/location list entries |
@@ -637,6 +638,98 @@ Now `ghw`, `ghj`, `ghs` etc. all work automatically.
 
 ---
 
+## Filetype-Aware Motions
+
+A single motion can adapt its entire pipeline based on the current buffer's filetype. This is useful when:
+
+- A filetype has no treesitter parser (e.g., fugitive's `gitcommit`)
+- A language needs a custom treesitter query (e.g., SQL with non-standard node types)
+- You want one keymap that behaves differently in different languages
+
+### How It Works
+
+Add `filetype_overrides` to your motion's `motion_state`. Each key is a filetype, and the value can override any pipeline module or motion_state field:
+
+```lua
+require("smart-motion").register_motion("]]", {
+  collector = "treesitter",          -- default: use treesitter
+  extractor = "pass_through",
+  filter = "filter_visible",
+  visualizer = "hint_start",
+  action = "jump_centered",
+  map = true,
+  modes = { "n" },
+  metadata = {
+    motion_state = {
+      ts_node_types = { "function_declaration", "function_definition" },
+      filetype_overrides = {
+        gitcommit = {                -- no TS parser → use patterns
+          collector = "patterns",
+          motion_state = {
+            patterns = {
+              "\\vmodified:\\s+\\zs\\S.*$",
+              "\\vnew file:\\s+\\zs\\S.*$",
+            },
+          },
+        },
+        sql = {                      -- has TS but needs custom query
+          motion_state = {
+            ts_query = [[(function_definition name: (identifier) @fn)]],
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+**What happens:**
+- In a Lua/Python/JS file → treesitter collector, matches `function_declaration`/`function_definition`
+- In a `gitcommit` buffer → patterns collector, matches modified file paths
+- In a SQL file → treesitter collector, but with a custom query instead of node types
+
+### What You Can Override
+
+An override can swap **any** pipeline module:
+
+| Field | What it swaps |
+|-------|---------------|
+| `collector` | Data source (e.g., `"treesitter"` → `"patterns"`) |
+| `extractor` | Target extraction (e.g., `"words"` → `"pass_through"`) |
+| `filter` | Target filtering |
+| `modifier` | Target enrichment |
+| `visualizer` | Hint display |
+| `action` | What happens on selection |
+| `motion_state` | Deep-merged into motion_state (patterns, ts_query, etc.) |
+
+### Using the Patterns Collector
+
+The `patterns` collector finds targets using vim regex. It reads two fields from `motion_state`:
+
+- **`patterns`** — Array of vim regex strings (required)
+- **`patterns_whole_line`** — If `true`, the entire matching line is the target (default `false`)
+
+```lua
+-- Jump to file paths
+motion_state = {
+  patterns = { "\\v\\f+" },
+}
+
+-- Jump to lines containing TODO (whole-line targets)
+motion_state = {
+  patterns = { "TODO" },
+  patterns_whole_line = true,
+}
+```
+
+Use `pass_through` as the extractor since the patterns collector already produces complete targets. All standard filters, visualizers, and actions work with pattern targets.
+
+### Operator Composition
+
+Filetype dispatch runs before the infer system. If you have a composable operator like `d` and a filetype-overridden motion like `]]`, pressing `d]]` in a gitcommit buffer automatically uses the pattern-based pipeline. No extra configuration needed.
+
+---
+
 ## Tips
 
 1. **Start simple.** Get a basic motion working, then add complexity.

docs/Pipeline-Architecture.md

@@ -59,12 +59,57 @@ The coroutine design enables:
 |-----------|----------------|
 | `lines` | Each line in the buffer with `text` and `line_number` |
 | `treesitter` | Syntax nodes matching configured types |
+| `patterns` | Targets matching vim regex patterns against buffer lines |
 | `diagnostics` | LSP diagnostic entries |
 | `git_hunks` | Git changed regions (via gitsigns or git diff) |
 | `quickfix` | Quickfix or location list entries |
 | `marks` | Vim marks (a-z local, A-Z global) |
 | `history` | Previous SmartMotion jump targets |
 
+### Patterns Collector
+
+The `patterns` collector finds targets using vim regex. It reads from `motion_state`:
+
+- **`patterns`** (string[]) — Array of vim regex strings to match
+- **`patterns_whole_line`** (boolean) — If `true`, the entire matching line is the target instead of just the match
+
+```lua
+motion_state = {
+  patterns = { "\\v\\f+" },  -- match file paths
+}
+```
+
+Multiple patterns are matched in order. Multiple matches per line are supported (the collector advances past each match). Invalid regex is safely caught via `pcall`.
+
+The patterns collector yields standard targets, so it composes with any extractor, filter, visualizer, and action. Use `pass_through` as the extractor since the collector already produces complete targets.
+
+### Filetype Dispatch
+
+A pre-pipeline middleware that swaps any pipeline module based on the current buffer's filetype. This allows a single motion to adapt its behavior per filetype — e.g., using regex patterns for filetypes without treesitter parsers.
+
+Configure it via `filetype_overrides` in a motion's `motion_state`:
+
+```lua
+motion_state = {
+  ts_node_types = { "function_declaration" },
+  filetype_overrides = {
+    gitcommit = {
+      collector = "patterns",
+      motion_state = {
+        patterns = { "\\vmodified:\\s+\\zs\\S.*$" },
+      },
+    },
+    sql = {
+      motion_state = {
+        ts_query = [[(function_definition name: (identifier) @fn)]],
+      },
+    },
+  },
+}
+```
+
+The override can swap any pipeline module (`collector`, `extractor`, `modifier`, `filter`, `visualizer`, `action`) and/or deep-merge `motion_state` fields. Overrides are per-motion, so different motions can have different filetype behavior. When no override matches the current filetype, the middleware is a no-op.
+
 ### Treesitter Collector Modes
 
 The `treesitter` collector is powerful. It supports four modes:

docs/Recipes.md

@@ -267,6 +267,7 @@ Collectors determine *where targets come from*.
 |------|--------|
 | `lines` | Visible buffer lines (default for most motions) |
 | `treesitter` | Treesitter AST nodes |
+| `patterns` | Vim regex matches against buffer lines |
 | `diagnostics` | LSP diagnostics |
 | `git_hunks` | Git changed regions |
 | `quickfix` | Quickfix or location list entries |