Improve fallback diagnostics and Vue/TypeScript indexing transparency

[jununfly]

This was generated by AI during triage.

What to build

User feedback from initializing and inspecting zcodegraph on a mixed Go + Vue repository (agentrq/agentrq). The tool was useful for codebase navigation, especially symbol lookup, call-path exploration, impact review, and getting oriented quickly. The main friction was that the successful index still reported degraded fallback health without enough detail to decide what to do next.

Observed run summary:

• zcodegraph init indexed 139 files, 3,097 nodes, and 4,678 edges.
• The run reported: Rust-hybrid appended 27 TypeScript fallback files and Fallback health: degraded.
• zcodegraph status later reported the index as up to date, but did not surface the degraded fallback context.
• zcodegraph doctor --engine rust-hybrid --bundle --last-run created a bundle and repeated the top-level reason, but did not make the next action obvious from the CLI summary.

The desired experience is that users and coding agents can understand which parts of the graph are trustworthy, which files fell back, why they fell back, and what action, if any, would improve the index.

User feedback

What worked well:

• Symbol-first navigation is much more useful than plain text search for understanding unfamiliar code.
• Call relationship and impact-style queries are valuable before editing shared backend/frontend paths.
• Returning related source in one exploration reduces context gathering time.
• The current Go/backend indexing looks immediately useful as a navigation layer.

What needs improvement:

• TypeScript/Vue fallback reporting should list affected files and reasons, not only the aggregate count.
• The health wording should explain practical impact: which query classes remain reliable and where users should verify with source or text search.
• status should preserve or point to the latest fallback health summary instead of only saying the index is up to date.
• Vue SFC and TypeScript support should be improved where possible, especially for script setup, component imports, router/store relationships, and frontend call/use sites.
• Longer term, cross-layer weak links would be valuable, such as backend API/view fields to frontend consumers.

Proposed vertical slices

1. Surface actionable fallback file details in doctor/status output.

   • Type: AFK
   • Blocked by: None
   • User story: As a user, I can see exactly which files fell back and why.

2. Explain fallback health impact in CLI summaries.

   • Type: AFK
   • Blocked by: None
   • User story: As a user, I can tell whether the index is safe to use for my current task.

3. Improve Vue/TypeScript indexing coverage for common SFC patterns.

   • Type: AFK or HITL depending on parser architecture decisions
   • Blocked by: fallback diagnostics are helpful but not strictly required
   • User story: As a frontend user, I get fewer fallback files and better component-level navigation.

4. Explore cross-layer API field usage hints.

   • Type: HITL
   • Blocked by: None
   • User story: As a full-stack user, I can trace backend API/schema fields toward frontend usage without expecting perfect static typing across languages.

Acceptance criteria

• When fallback health is degraded, CLI output identifies the affected files or points to a generated artifact that lists them.
• Each fallback entry includes a reason category, such as unsupported syntax, parser failure, missing config, or fallback-by-design.
• zcodegraph status either shows the last known fallback summary or clearly links to the most recent diagnostic bundle.
• Health output distinguishes between index freshness and index quality.
• Documentation or CLI help explains what users should do when fallback health is degraded.
• Vue/TypeScript fallback reduction can be measured on a mixed Go + Vue repository or a comparable fixture.

Blocked by

None - can start immediately.

[jununfly]

Status update after PR #674:\n\n#674 improves diagnostic trust for corrupted graph databases, but this issue remains open. The remaining scope is fallback transparency for mixed Go/Vue/TypeScript projects: affected fallback files/reasons, status quality vs freshness, and measurable Vue/TypeScript fallback reduction.

[jununfly]

Implemented by PR #675 and merged into main.\n\n#675 closes the fallback transparency part of this issue: status now distinguishes freshness from graph quality, exposes top fallback file/reason groups, points users to the generated per-file diagnostics artifact, and documents when to use init/index/sync/status/doctor.\n\nVue/TypeScript parser coverage reduction was explicitly scoped out of this PR as a future measurable fallback-reduction slice; the diagnostics transparency and workflow acceptance criteria are now complete.