draft hcl2 tree query system and hq cli

Author: kkozik-amplify

CLAUDE.md

@@ -28,6 +28,17 @@ The **Direct** pipeline (`parse_to_tree` → `transform` → `to_lark` → `reco
 | `cli/helpers.py` | File/directory/stdin conversion helpers |
 | `cli/hcl_to_json.py` | `hcl2tojson` entry point |
 | `cli/json_to_hcl.py` | `jsontohcl2` entry point |
+| `cli/hq.py` | `hq` CLI entry point — query dispatch, formatting, optional operator |
+| `hcl2/query/__init__.py` | Public query API exports |
+| `hcl2/query/_base.py` | `NodeView` base class, view registry, `view_for()` factory |
+| `hcl2/query/path.py` | Structural path parser (`PathSegment`, `parse_path`, `[select()]`, `type:name`) |
+| `hcl2/query/resolver.py` | Path resolver — segment-by-segment with label depth, type filter, FunctionCallView |
+| `hcl2/query/pipeline.py` | Pipe operator — `split_pipeline`, `classify_stage`, `execute_pipeline` |
+| `hcl2/query/builtins.py` | Built-in transforms: `keys`, `values`, `length` |
+| `hcl2/query/diff.py` | Structural diff between two HCL documents |
+| `hcl2/query/predicate.py` | `select()` predicate tokenizer, recursive descent parser, evaluator |
+| `hcl2/query/safe_eval.py` | AST-validated Python expression eval for hybrid/eval modes |
+| `hcl2/query/introspect.py` | `--describe` and `--schema` output generation |
 
 `hcl2/__main__.py` is a thin wrapper that imports `cli.hcl_to_json:main`.
 
@@ -141,4 +152,4 @@ Hooks are defined in `.pre-commit-config.yaml` (includes black, mypy, pylint, an
 
 ## Keeping Docs Current
 
-Update this file when architecture, modules, API surface, or testing conventions change. Also update `README.md` and `docs/usage.md` when changes affect the public API, CLI flags, or option fields.
+Update this file when architecture, modules, API surface, or testing conventions change. Also update `README.md` and the docs in `docs/` (`01_getting_started.md`, `02_querying.md`, `03_advanced_api.md`, `04_hq.md`) when changes affect the public API, CLI flags, or option fields.

README.md

@@ -67,12 +67,18 @@ res.block("tags", Name="HelloWorld")
 hcl_string = hcl2.dumps(doc.build())
 ```
 
-For the full API reference, option dataclasses, intermediate pipeline stages, and more examples
-see [docs/usage.md](https://github.com/amplify-education/python-hcl2/blob/main/docs/usage.md).
+### Documentation
+
+| Guide | Contents |
+|---|---|
+| [Getting Started](docs/01_getting_started.md) | Installation, load/dump, options, CLI converters |
+| [Querying HCL (Python)](docs/02_querying.md) | DocumentView, BlockView, tree walking, view hierarchy |
+| [Advanced API](docs/03_advanced_api.md) | Pipeline stages, Builder |
+| [hq Reference](docs/04_hq.md) | `hq` CLI — structural queries, hybrid/eval, introspection |
 
 ### CLI Tools
 
-python-hcl2 ships two command-line converters:
+python-hcl2 ships three command-line tools:
 
 ```sh
 # HCL2 → JSON
@@ -84,9 +90,13 @@ hcl2tojson terraform/ output/          # converts a directory
 jsontohcl2 output.json                 # prints HCL2 to stdout
 jsontohcl2 output.json main.tf         # writes to file
 jsontohcl2 output/ terraform/          # converts a directory
+
+# Query HCL2 files
+hq 'resource.aws_instance.main.ami' main.tf
+hq 'variable[*]' variables.tf --json
 ```
 
-Both commands accept `-` as PATH to read from stdin. Run `hcl2tojson --help` or `jsontohcl2 --help` for the full list of flags.
+All commands accept `-` as PATH to read from stdin. Run `--help` on any command for the full list of flags.
 
 ## Building From Source