feat(framework): add Vue SFC processing for search/trace with source remapping

[mika76]

Closes #153. Related to #146.

This PR adds Vue .vue support for indexing/search/trace through an extensible framework processor platform, and introduces a complementary property/state usage graph (refs) for Vue/JS/TS workflows.

What this PR delivers

1) Framework processor platform + Vue implementation

• Added framework processing architecture:
  • FrameworkProcessor contract
  • ProcessorRegistry
  • shared transform + mapping contracts
• Implemented VueProcessor end-to-end using @vue/compiler-sfc via Node.
• Added scaffold processors for:
  • svelte
  • astro
  • solid
    (registered, documented extension points, intentionally non-functional in this pass)

2) Indexing/search/trace integration

• Indexing uses transformed framework text for embeddings.
• Search results keep original source snippets and .vue file paths.
• Trace extraction runs on transformed output, with remapping back to original file/line.
• Vue style v-bind(...) support added (synthetic style-binding refs).

3) Trace correctness improvements

• Fixed JS/TS declaration self-call artifact.
• Improved symbol disambiguation for same-name symbols by file context.
• Added synthetic Vue template read callers for template-driven access visibility.

4) New refs subsystem (property/state usage)

To complement call-graph trace, this PR adds property/state usage tracing:

• CLI:
  • grepai refs readers <symbol>
  • grepai refs writers <symbol>
  • grepai refs graph <symbol>
• MCP tools:
  • grepai_refs_readers
  • grepai_refs_writers
  • grepai_refs_graph
• Agent setup instructions and docs updated to clarify trace vs refs.

Coverage includes Vue/JS/TS usage patterns:

• dot access (store.uid)
• bracket access (store["uid"])
• Composition API aliases (toRefs / storeToRefs, alias + .value read/write)

5) Noise reduction for refs

Added filtering to reduce JS/Vue property noise:

• filters obvious builtin/global roots (Math, Object, console, window, document, etc.)
• filters Vue/runtime internals ($refs, $slots, $attrs, ...)
• keeps app-level state keys (uid, role, etc.)

Config

framework_processing block:

• enabled
• mode (auto|require|off)
• node_path
• per-framework flags (vue, svelte, astro, solid)

Defaults remain:

• mode auto
• Vue enabled
• scaffolded frameworks disabled

Tests / validation

Added/expanded coverage for:

• registry routing + mode behavior (auto/require/off)
• Vue compile/fallback/remap behavior
• scaffold processor behavior
• trace disambiguation + template read synthesis
• refs extraction and kind filtering
• CLI refs integration-style test
• MCP schema coverage for refs tools

Integration scripts:

• scripts/test-vue-framework-processing.sh
• scripts/test-vue-framework-matrix.sh
  • now includes Composition API + bracket refs assertions
  • includes fallback refs assertions

Validation performed:

• go test ./trace ./cli ./mcp passing
• Vue matrix script passing end-to-end locally

Notes

• trace remains call-graph oriented.
• refs is additive for property/state read/write relationships.
• Svelte/Astro/Solid are scaffolded only in this PR; full implementations can follow without architectural refactor.

I used Codex (GPT-5) to help with implementation, test expansion, and cleanup.

[mika76]

Rebased onto latest main and resolved merge conflicts (mainly around cli/watch.go plus config changes). Also re-ran focused tests after conflict resolution:

• go test ./cli ./config ./framework ./indexer ./trace ✅
• Branch is updated on my fork and PR should now be conflict-free again.

[codecov]

Codecov Report

❌ Patch coverage is 56.36516% with 521 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.49%. Comparing base (a322537) to head (6030422).
⚠️ Report is 95 commits behind head on main.

Files with missing lines	Patch %	Lines
mcp/server.go	24.29%	187 Missing ⚠️
cli/refs.go	34.21%	91 Missing and 9 partials ⚠️
trace/extractor.go	75.25%	27 Missing and 22 partials ⚠️
framework/vue_processor.go	78.12%	32 Missing and 10 partials ⚠️
cli/trace.go	36.17%	26 Missing and 4 partials ⚠️
framework/map.go	34.09%	21 Missing and 8 partials ⚠️
cli/watch.go	68.75%	15 Missing and 5 partials ⚠️
framework/registry.go	76.05%	15 Missing and 2 partials ⚠️
indexer/indexer.go	62.79%	11 Missing and 5 partials ⚠️
trace/store.go	69.69%	5 Missing and 5 partials ⚠️
... and 4 more

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #157       +/-   ##
===========================================
+ Coverage   27.16%   47.49%   +20.33%     
===========================================
  Files          32       80       +48     
  Lines        3711    15173    +11462     
===========================================
+ Hits         1008     7207     +6199     
- Misses       2620     7216     +4596     
- Partials       83      750      +667     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mika76]

Follow-up update (latest head: 6030422).

Added in latest pushes

• Property/state usage tracing alongside call graph:
  • CLI: grepai refs readers|writers|graph
  • MCP: grepai_refs_readers, grepai_refs_writers, grepai_refs_graph
• Vue refs coverage expanded for:
  • toRefs/storeToRefs alias + .value read/write
  • bracket access (store["key"])
• Refs noise filtering:
  • suppresses builtin/global roots (Math, Object, console, window, etc.)
  • suppresses Vue runtime internals ($refs, $slots, $attrs, ...)
• Matrix integration script now asserts refs behavior (including fallback mode).
• Docs now clarify trace (call graph) vs refs (property/state reads/writes).

Computed handling (explicit)

• Computeds/methods remain trace symbols (call graph side).
• Their internal state dependencies are captured through refs (read/write side).
• Vue template usage still contributes synthetic template-read visibility where applicable.

Validation run

• go test ./trace ./cli ./mcp
• ./scripts/test-vue-framework-matrix.sh (green end-to-end)

[mika76]

Merged the latest origin/main into this branch, resolved the trace/config conflicts, and added MCP refs handler tests for missing symbol, invalid format, and happy-path readers/graph responses.

[mika76]

Added shell completion support for the new refs commands. This wires dynamic --workspace and --project completion for refs readers/writers/graph and adds CLI completion tests using Cobra __complete coverage.

[mika76]

Added a follow-up commit on this branch with two cleanups from local validation:

• normalize and dedupe Vue compiler-missing fallback warnings so missing @vue/compiler-sfc logs once without stack spam
• restore in-place watch --no-ui progress updates while making foreground log lines clear and redraw the progress line instead of breaking it

Also added regression coverage for the Vue compiler resolution path and the plain watch progress behavior.