AGENTS Guide for ASTQuery (Raku 6.d)
- Setup: `zef install --/test --test-depends --deps-only .` (installs deps)
- Install test runner: `zef install --/test App::Prove6`
- Run all tests: `prove6 -I. t`
- Run single test file: `prove6 -I. t/02-ASTQuery.rakutest` (or `raku -I. t/<file>`)
- Syntax check (lint): `raku -I. -c lib/ASTQuery.rakumod lib/ASTQuery/*.rakumod`
- Install locally: `zef install .` (optional)
- CLI: `raku -I. bin/ast-query.raku` (if needed)
- Imports: Put `use` at top; declare `unit module|class` first; export with `is export`.
- Formatting: Use tabs for indentation; one `use` per line; keep lines readable (<100 cols); trailing commas in multi-line lists.
- Types: Prefer typed signatures (`Str`, `Bool`, `Callable`), subsets + `where`; use `proto`/`multi` dispatch as in repo.
- Naming: CamelCase for types/modules; hyphenated method names (e.g., `validate-descendant`); lower-case sub names; ALLCAPS env vars.
- Errors: Use `fail` for programmer errors; return `False` for predicate no-match; wrap risky code in `CATCH { default { ... } }`.
- Debug: Gate notes behind `%*ENV<ASTQUERY_DEBUG>`; use `note`, not `say`, in library code.
- Tests: Use `use Test; done-testing;` with `.rakutest` files; prefer `isa-ok`, `is-deeply`, `ok`.
- AST use: `use experimental :rakuast` where needed; avoid breaking matcher/API gists.
- Public API: Modify exports in `lib/ASTQuery.rakumod` carefully; keep signatures stable.
- Docs: Keep Pod6 in modules; update README examples if changing query syntax.
- Cursor/Copilot: No Cursor or Copilot rule files present.
- CI parity: Match GitHub Actions: `prove6 -I. t` on macOS/Ubuntu latest Raku.
- Coverage: `zef install --/test App::RaCoCo` (once). Run `raku -I. tools/coverage.raku` to compute total coverage; it prints `percent=<number>`.
- Pre-commit check: Before every commit, run `raku -I. tools/coverage-check.raku` which updates `.coverage-baseline` and tells you if coverage decreased vs. last commit.
- Commits: Follow Conventional Commits (feat, fix, docs, chore, refactor, test, perf, build, ci, revert); imperative mood; optional scope; add body/footers when relevant (e.g., BREAKING CHANGE:, Closes #123).
- Independent of what language is being used on conversation, the generated code, comments, documentation, etc will ALWAY be in English.
