feat: Go to Declaration for Qiq helper calls (1.x HelperLocator + 2.x/3.x Helpers)

[jingu]

Summary

Cmd/Ctrl+click on a Qiq helper call ({{ helperName(...) }} or {{ $this->helperName(...) }}) now navigates to the helper's PHP declaration. Covers both Qiq helper styles:

• Qiq 1.x — HelperLocator (manual config): QiqHelperRegistry scans the bootstrap file(s) nominated in Settings > Languages & Frameworks > Qiq Templates, reading each $locator->set('name', closure) and resolving the target from the closure's declared return type or a return new ClassName(...) statement → navigates to the Qiq\Helper\<X>::__invoke/class.
• Qiq 2.x/3.x — Helpers subclass (automatic): QiqHelpersClassResolver discovers every project-defined subclass of Qiq\Helpers (the official custom-helper style: public methods on a class extending Qiq\Helper\Html\HtmlHelpers, passed via Template::new(helpers: ...)) through PhpIndex and resolves name → public method. No configuration needed; self-gates (a 1.x project has no \Qiq\Helpers). Library classes under \Qiq\ are skipped — built-ins already resolve via the bundled stub.

Both paths also feed QiqHelperInspectionSuppressor, which suppresses PhpStorm's "undefined function/method" warnings for resolvable helper calls inside Qiq files (mirroring the bundled Blade support).

Settings UI gains a file-chooser list (multi-select, .php only) for the 1.x helper bootstrap files; paths are stored relative to the project base dir when possible.

Why GotoDeclarationHandler (not PsiReferenceContributor)

Function/method call names carry their own resolution and never aggregate contributed references, so a PsiReferenceContributor is ignored for them. gotoDeclarationHandler is the correct extension point and works inside injected PHP.

Injection fix (RAW_CONTENT)

{{= asset(...) }} previously had its leading a stripped as the {{a }} escape modifier, corrupting the injected call to sset(...). Helper names starting with h/a/j/u/c (asset, currentUrl, upper, …) now pass through verbatim:

• RAW_CONTENT ({{= }}) is emitted as a plain <?= ... ?> echo.
• The legacy text-modifier strip now requires a standalone modifier byte followed by whitespace.

Test plan

• ./gradlew test — all green (QiqHelperRegistryTest, QiqPhpInjectorTest incl. new rawEchoHelperCallStartingWithEscapeLetterIsNotStripped)
• ./gradlew buildPlugin
• Manual verification in PhpStorm against a real BEAR.Sunday/Qiq 1.x project: helper Cmd+click jumps to the helper class; the leading-letter corruption is fixed; undefined-function warning suppressed for registered helpers
• Manual verification against a Qiq 2.x/3.x project (Helpers subclass auto-discovery) — pending

Notes / limitations

• 1.x resolver handles set/setFactory/register with an inline closure/arrow whose target is a declared return type or new X(...). Dynamic names, callable-array/class-string/variable factories, and indirect ($container->make(...)) factories are not resolved.
• 2.x/3.x resolver indexes public, non-static, non-magic own methods of Qiq\Helpers subclasses, cached against PsiModificationTracker.
• The PhpIndex-based 2.x/3.x discovery is not covered by an automated test (needs an indexed fixture project); verified by compile/build and to be confirmed manually.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds PhpStorm navigation and inspection support for Qiq “helper calls” by scanning user-configured PHP bootstrap files that register helpers via HelperLocator::set(), and fixes a RAW-content injection regression for helper names starting with escape-modifier letters.

Changes:

• Implement Go to Declaration for Qiq helper calls via a GotoDeclarationHandler, backed by a new QiqHelperRegistry scanner.
• Add settings UI + persistence for configuring helper bootstrap PHP files, and invalidate the helper scan cache on apply.
• Fix {{= ... }} RAW echo injection so helper names like asset(...) aren’t corrupted by legacy escape-modifier stripping; add regression tests.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/test/kotlin/io/github/jingu/idea_qiq_plugin/inject/QiqPhpInjectorTest.kt	Adds regression coverage for RAW echo helper calls starting with escape letters.
src/test/kotlin/io/github/jingu/idea_qiq_plugin/helper/QiqHelperRegistryTest.kt	Adds unit tests for helper name → class scanning across multiple PHP factory shapes.
src/main/resources/META-INF/plugin.xml	Registers the new goto-declaration handler and PHP inspection suppressor.
src/main/resources/messages/QiqBundle.properties	Adds user-facing strings for helper bootstrap file settings UI.
src/main/kotlin/io/github/jingu/idea_qiq_plugin/settings/QiqSettingService.kt	Persists helper bootstrap file list and resolves configured paths to VirtualFiles.
src/main/kotlin/io/github/jingu/idea_qiq_plugin/settings/QiqProjectConfigurable.kt	Adds UI for selecting and storing helper bootstrap files (multi-select).
src/main/kotlin/io/github/jingu/idea_qiq_plugin/navigation/QiqHelperGotoDeclarationHandler.kt	Implements helper-call navigation in injected PHP via GotoDeclarationHandler.
src/main/kotlin/io/github/jingu/idea_qiq_plugin/lang/QiqInjectionSupport.kt	Centralizes “is this element in a Qiq template (incl. injected PHP)” detection.
src/main/kotlin/io/github/jingu/idea_qiq_plugin/inspection/QiqHelperInspectionSuppressor.kt	Suppresses undefined function/method inspections for resolvable helper calls in Qiq.
src/main/kotlin/io/github/jingu/idea_qiq_plugin/inject/QiqPhpInjector.kt	Fixes RAW-content echo injection to avoid stripping leading helper-name characters.
src/main/kotlin/io/github/jingu/idea_qiq_plugin/helper/QiqHelperRegistry.kt	Adds the helper registry and static scanner with caching keyed by file modification stamps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.