Add .[] as jq-compatible alias for [*] and document jq interop (#283)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kkozik-amplify

docs/04_hq.md

@@ -44,7 +44,7 @@ type_filter := IDENTIFIER
 - `name` matches block types and attribute names
 - `type:name` matches only nodes of the given type (e.g. `function_call:length`)
 - `name~` skips all block labels, going straight to the body (see below)
-- `[*]` selects all matches at that level
+- `[*]` or `.[]` selects all matches at that level (`.[]` is a jq-compatible alias)
 - `[N]` selects the Nth match (zero-based)
 - `[select(PRED)]` filters matches using a predicate (see below)
 
@@ -612,6 +612,53 @@ hq 'resource[*] | {type: .block_type, name: .name_labels}' main.tf --json
 hq 'variable[select(.default)]::name_labels[0] + " = " + str(_.attribute("default").value)' variables.tf --value
 ```
 
+## Piping to jq
+
+hq handles structural HCL navigation (blocks, labels, type filters, predicates). For data transforms on the results, pipe `--json` or `--ndjson` output to jq:
+
+```sh
+# Defaults — fill missing values
+hq 'resource~[*] | {name: .name_labels, tags}' main.tf --json | jq '.tags // "none"'
+
+# Reshaping — extract specific fields into arrays
+hq 'resource[*]' main.tf --json | jq '[.block_type, .name]'
+
+# Mapping — transform each result
+hq 'module~[*] | .source' dir/ --ndjson | jq -r 'ascii_downcase'
+
+# Filtering on JSON values
+hq 'resource~[*]' main.tf --ndjson | jq 'select(.count > 3)'
+
+# Aggregation — group or sort across results
+hq 'resource[*]' dir/ --ndjson | jq -s 'group_by(.block_type)'
+```
+
+**Mental model:** hq navigates HCL structure (block types, labels, attributes, nesting). Once you have `--json` output, you're in jq's world — use jq for arithmetic, string transforms, reshaping, defaults, and aggregation.
+
+## Coming from jq
+
+| jq | hq equivalent | Notes |
+|---|---|---|
+| `.key` | `.key` | Same syntax |
+| `.[]` | `.[]` or `[*]` | `.[]` is an alias for `[*]` |
+| `.[N]` | `[N]` | Zero-based index |
+| `select(.x == "y")` | `[select(.x == "y")]` | Bracket or pipe syntax |
+| `keys` | `\| keys` | Pipe stage |
+| `length` | `\| length` | Pipe stage |
+| `has("key")` | `[select(has("key"))]` | Inside select predicates |
+| `contains("str")` | `[select(.field \| contains("str"))]` | Inside select predicates |
+| `test("regex")` | `[select(.field \| test("regex"))]` | Inside select predicates |
+| `{a, b}` | `{a, b}` | Object construction |
+| `{newkey: .old}` | `{newkey: .old}` | Renamed keys |
+| `map(.f)` | — | `--json \| jq 'map(.f)'` |
+| `.x // "default"` | — | `--json \| jq '.x // "default"'` |
+| `[.x, .y]` | — | `--json \| jq '[.x, .y]'` |
+| `group_by(.f)` | — | `--ndjson \| jq -s 'group_by(.f)'` |
+| `sort_by(.f)` | — | `--ndjson \| jq -s 'sort_by(.f)'` |
+| `if-then-else` | — | `--json \| jq 'if ...'` or hybrid (`::`) mode |
+
+Features unique to hq (no jq equivalent): block type navigation (`resource.aws_instance`), label traversal, skip labels (`~`), type qualifiers (`function_call:name`), recursive descent (`..`), `--describe` / `--schema` introspection.
+
 ## See Also
 
 - [hq Examples](05_hq_examples.md) — validated real-world queries by use case

hcl2/query/path.py

@@ -41,6 +41,9 @@ def parse_path(path_str: str) -> List[PathSegment]:  # pylint: disable=too-many-
     if not path_str or not path_str.strip():
         raise QuerySyntaxError("Empty path")
 
+    # jq compat: .[] is an alias for [*]
+    path_str = path_str.replace(".[]", "[*]")
+
     segments: List[PathSegment] = []
     parts = _split_path(path_str)
 

test/unit/query/test_path.py

@@ -189,3 +189,25 @@ def test_escaped_quote_in_string(self):
         segments = parse_path('*[select(.name == "a\\"b")]')
         self.assertEqual(len(segments), 1)
         self.assertIsNotNone(segments[0].predicate)
+
+    # jq compat: .[] as alias for [*]
+
+    def test_jq_iterate_alias(self):
+        """resource.[] is equivalent to resource[*]"""
+        segments = parse_path("resource.[]")
+        expected = parse_path("resource[*]")
+        self.assertEqual(segments, expected)
+
+    def test_jq_iterate_alias_chained(self):
+        """a.b.[] normalizes to a.b[*]"""
+        segments = parse_path("a.b.[]")
+        self.assertEqual(len(segments), 2)
+        self.assertEqual(segments[0].name, "a")
+        self.assertEqual(segments[1].name, "b")
+        self.assertTrue(segments[1].select_all)
+
+    def test_jq_iterate_alias_with_continuation(self):
+        """resource.[].tags normalizes to resource[*].tags"""
+        segments = parse_path("resource.[].tags")
+        expected = parse_path("resource[*].tags")
+        self.assertEqual(segments, expected)