skills/das_macros: document AST-match helpers, qmatch idiom, push cluster consolidation

[borisbat]

Summary

Codifies the patterns established by PRs #2793-#2799 (the linq_fold / sqlite_linq / ast_match harvest ladder) so future macro work follows the documented forms instead of rediscovering them.

Three new sections:

1. "Shared AST-match helpers" — table of 11 public helpers in daslib/ast_match.das + daslib/templates_boost.das (match_call_in_module, match_call_in_linq, peel_lambda_* 4 forms, peel_tuple_field_read, extract_const_string, qn, qm_peel_ref2value, push_block_list) with signatures + when-to-reach-for-each. Includes a "when patterns apply vs don't" note: introspection-heavy files (linq_fold, sqlite_linq, ast_match) benefit; emit-only files (decs_boost, the emitter half of templates_boost) don't.

2. "qmatch — predicate-style pattern matching" — anti-pattern (hand-rolled is X / as X cascades) vs preferred predicate form. Documents that $e/$f/$v/$i tags bind to pre-declared outer variables, not result-struct fields (a subtle but easy-to-get-wrong API shape). Points to sqlite_linq.das for 37+ adoption sites + tests/ast_match/test_qmatch_*.das for grammar exercises.

3. "Push cluster consolidation" (new subsection under "qmacro vs quote") — consecutive arr |> push <| qmacro_expr() { ... } runs into the same array collapse into one emission via either Form A (push_from + qmacro_block_to_array, preferred, no clone) or Form B (push_block_list + qmacro_block, clones, use when the source block stays alive). Includes "when NOT to collapse" guard.

One section updated:

• "Peel ExprRef2Value before qmatch" now routes through qm_peel_ref2value (single source of truth) instead of showing the manual if-peel snippet. Adds note on why the helper still uses while-peel (conservative until ast_block_folding.cpp synthesis paths are audited).

PR 6 (decs_boost migration from the original plan) intentionally skipped:
Audit confirmed decs_boost has zero hand-rolled is_*_call helpers, zero qname construction, zero ExprRef2Value while-loops, zero push qmacro_expr clusters, and zero peel_lambda candidates. The file is mostly code-generation plumbing, not AST introspection — the migration would manufacture work. The "when patterns apply" note in the new helpers section codifies this finding so future audits start with the question instead of mechanical search.

Test plan

• Read the doc cold — section flow is logical (probing → matching → emitting), helper signatures match daslib/ast_match.das:2199-2332 verbatim, qmatch example uses the actual var lhs, rhs : ExpressionPtr; qmatch(...).matched shape verified against tests/ast_match/test_capture_e.das
• Anchor links resolve: #peel-exprref2value-before-qmatch and #push-cluster-consolidation are GitHub-flavored markdown auto-anchors that match the new section headings
• All code samples are syntactically valid daslang gen2 (multi-var decl var lhs, rhs : ExpressionPtr exists in 5+ codebase sites incl. daslib/random.das:85)
• No code/test impact — doc-only PR

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates skills/das_macros.md to document established macro/AST-introspection patterns, including shared AST-match helpers, the qmatch idiom, and how to consolidate consecutive qmacro push clusters.

Changes:

• Added a “Shared AST-match helpers” section describing public helpers from daslib/ast_match.das and daslib/templates_boost.das.
• Added a “qmatch — predicate-style pattern matching” section with recommended usage and tag explanations.
• Added “Push cluster consolidation” guidance for collapsing consecutive qmacro_expr pushes, and updated the ExprRef2Value peeling section to reference qm_peel_ref2value.

Comments suppressed due to low confidence (1)

skills/das_macros.md:340

• This subsection states that qmatch can't match through ExprRef2Value and that auto-peel inside qmatch is still TODO, but the matcher already peels ExprRef2Value on both source and pattern sides via qm_peel_ref2value emitted by generate_match (and has dedicated transparency tests). Please update this section to avoid sending readers toward unnecessary (or contradictory) manual peeling, and refocus it on cases where qm_peel_ref2value is needed outside qmatch (e.g., hand-written is/as probes).

Post-Mode-2-expansion AST walking will see field reads wrapped in `ExprRef2Value`. `qmatch` is RTTI-strict — it matches `ExprField` but not `ExprRef2Value(ExprField(...))`. **Route through `qm_peel_ref2value`** (the single source of truth in `daslib/ast_match.das`) instead of hand-rolling either a `while`-peel or an `if`-peel:

```das
require daslib/ast_match

qm_peel_ref2value(node)
if (node == null) {
    macro_error(prog, at, "_where: ExprRef2Value with null subexpr")
    return ""
}
// now `qmatch(node, _.$f(name))` etc. work as expected

qm_peel_ref2value currently uses while (e is ExprRef2Value) rather than single-if-peeling. The conservative loop is intentional until block-folding is fully audited — tests/ast_match/test_ref2value_skip.das exercises a triple-wrap shape, and src/ast/ast_block_folding.cpp synthesis paths could theoretically produce a nested wrapper. Once that audit lands, the helper switches to single-if peel in one place and every consumer follows automatically.

Auto-peel inside qmatch itself remains a TODO documented in daslib/ast_match.das. Until then, every analyzer entry point that takes an expression coming out of post-expansion (predicate body, projection body, classifier helpers like is_const_or_captured_var) needs the qm_peel_ref2value call at the top.

</details>



---

💡 <a href="/GaijinEntertainment/daScript/new/master?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.