feat(v0.19): make --spi pay off — framework metadata + retrieval boost for Hono/Fastify/tRPC/Prisma

[mohanagy]

Summary

Closes the gap between "SPI substrate exists" and "users see token savings." Two complementary pieces.

1. Confirmed: framework metadata flows end-to-end with --spi

My earlier claim that the graph.json serializer was dropping framework_role / route_path was wrong — it was a bad test assertion (whitespace formatting mismatch). Tightened the v0.18 test to assert what's actually produced:

{
  "label": "listUsers()",
  "framework": "express",
  "framework_role": "express_route",
  "node_kind": "route",
  "route_path": "/users",
  ...
}

The serializer in src/pipeline/export.ts already spreads all node attributes via ...attributes. No serializer change needed.

2. Retrieval boost for the v0.17 substrates

frameworkBoostForNode() in src/runtime/retrieve.ts previously only handled express / redux / reactRouter / nest / next. v0.17 added 4 more substrates (Hono / Fastify / tRPC / Prisma) but retrieval ignored their framework_role values.

Now wired:

• New profile slots: hono / fastify / trpc / prisma
• New intents: pluginIntent / procedureIntent / queryIntent / mutationIntent / subscriptionIntent / modelIntent
• Boost rules for all 11 new framework_role values (hono_route, hono_middleware, hono_app, fastify_route, fastify_plugin, fastify_app, trpc_procedure_query/mutation/subscription, trpc_router, prisma_client)
• Compatibility filter: activeFrameworksForProfile now registers hono / fastify / trpc / prisma so framework-compatible filtering recognises them
• Express disambiguation: Express boost is suppressed when Hono or Fastify are explicit in the question (prevents misrouting "show me hono routes" to Express handlers)

Token / benchmark impact

Framework-shaped questions ("show me hono routes", "what tRPC mutations exist", "find the Prisma client") now favour the structurally-correct nodes via framework_role boost. Concretely:

• Fewer plain function/class matches push the substrate-correct nodes off the budget cutoff
• The user-visible context_pack response surfaces the right nodes inside budget instead of bumping it
• Pure code-comprehension queries are unaffected (no boost fires)

Test plan

• npm run typecheck clean
• npm run build clean
• npm run test:run — 1817/1817 pass (110 files)
• New tests cover Hono/Fastify/tRPC/Prisma boost paths + negative case (unrelated question gets no boost)
• v0.18 test tightened to actually assert framework metadata in graph.json

Summary by CodeRabbit

• New Features

  • Extended framework detection and support for Hono, Fastify, tRPC, and Prisma alongside existing frameworks.
  • Improved retrieval ranking and context suggestions based on detected framework patterns and roles.

• Tests

  • Added comprehensive framework-aware retrieval validation tests to ensure accurate context ranking across multiple framework substrates.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 683ab116-2aa5-44ea-a5fa-7336cd41180a

📥 Commits

Reviewing files that changed from the base of the PR and between 03c84b8 and cf59af9.

📒 Files selected for processing (3)

• src/runtime/retrieve.ts
• tests/unit/generate-spi-flag.test.ts
• tests/unit/retrieve-framework-boost-v0-19.test.ts

---

📝 Walkthrough

Walkthrough

This PR extends the framework-aware retrieval system to recognize and boost framework-specific nodes for Hono, Fastify, tRPC, and Prisma. The runtime retrieval module gains new profile types, intent signals, framework selection logic with precedence rules, and dedicated node boost scoring. Tests validate SPI attribute propagation and framework-specific retrieval behavior.

Changes

Framework-Aware Retrieval Boost Extension

Layer / File(s)	Summary
Framework Question Profile Type Extensions src/runtime/retrieve.ts	FrameworkQuestionProfile interface extends with boolean fields for Hono, Fastify, tRPC, and Prisma framework shaping; adds new intent flags for plugin/procedure/query/mutation/subscription/model.
Framework Intent Detection and Active Frameworks src/runtime/retrieve.ts	buildFrameworkQuestionProfile adds explicit-question detection and intent signal expansion for the four new frameworks; activeFrameworksForProfile includes them in the active set when profile flags are true.
Framework Selection with Precedence Rules src/runtime/retrieve.ts	Framework selection logic treats Hono/Fastify as higher-priority signals that suppress Express; expanded frameworkShaped gating covers all four new substrates.
Framework-Specific Node Boost Rules src/runtime/retrieve.ts	frameworkBoostForNode adds dedicated boost rules mapping framework roles (Hono route/middleware/app, Fastify route/plugin/app, tRPC procedure query/mutation/subscription/router, Prisma client/model_access) to score adjustments.
SPI Attribute Propagation Validation tests/unit/generate-spi-flag.test.ts	Express/SPI test now parses graph.json and validates that framework, framework_role, node_kind, and route_path attributes are correctly serialized on nodes.
Framework Boost Test Suite Infrastructure tests/unit/retrieve-framework-boost-v0-19.test.ts	Establishes v0.19 framework-boost test suite with sandboxed file creation, graph generation/loading, and per-test setup/teardown scaffolding.
Framework-Specific Boost Test Cases tests/unit/retrieve-framework-boost-v0-19.test.ts	End-to-end tests for Hono routes, Fastify plugins, tRPC mutations/queries, and Prisma client usage verify positive framework_boost scoring; control test ensures non-framework questions do not trigger high boosts.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• mohanagy/graphify-ts#127: Introduces SPI pipeline that projects framework_role and framework metadata consumed by this PR's retrieval boost logic.
• mohanagy/graphify-ts#126: Release PR packaging and documenting the same framework substrate implementations (Hono, Fastify, tRPC, Prisma) added in this PR.
• mohanagy/graphify-ts#128: Related SPI integration work that ships framework metadata into graph.json, enabling the framework/framework_role assertions in this PR's tests.

Poem

🐰 Four frameworks now boost with cheer,
Hono, Fastify, tRPC here!
Prisma joins the retrieval dance,
With profile types and role-based stance.
Intent signals bloom and scores advance! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: extending framework metadata and retrieval boost support to four new substrates (Hono, Fastify, tRPC, Prisma) as part of making the --spi flag more effective.
Description check	✅ Passed	The description is well-structured with clear sections covering both pieces of work, token impact, and test plan. It includes a summary, implementation details, testing verification, and checklist items completed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/v0.19-spi-payoff

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}