perf: reuse workspace paths and parsed files across example checks

[LadyBluenotes]

🎯 Changes

intent validate typechecks skill examples once per library. In a workspace with many libraries, each of those checks repeated two pieces of work whose result does not change during a run:

• Workspace package map. workspacePaths resolved every workspace pattern again for each library. TanStack Table's examples/**/* pattern covers 2,379 directories and 400 packages, and the scan ran once for each library with examples.
• Parsed source files. Each library gets its own TypeScript program, and each program parsed the TypeScript lib files and the library sources again.

checkSkillBlocks now accepts a cache that lives for one run. validate and describeSkillExamples create it and pass it to every library check. It holds the workspace package map and the parsed non-example source files. Example blocks are never cached, because their virtual file names repeat between libraries.

Only the TypeScript 6 compiler path reuses parsed files. The TypeScript 7 path reuses the workspace package map.

Result

intent validate at the root of TanStack Table (39 skills, 15 libraries with examples), five alternating runs on the same machine:

	Wall time	CPU (user)
Before	12.1 to 14.7 s	15.0 to 17.2 s
After	4.2 to 5.4 s	7.4 to 8.6 s

The validation output is byte-identical before and after.

Summary by CodeRabbit

• Performance
  • Validation reuses workspace mappings and parsed TypeScript files across checks in the same run, while keeping validation results unchanged.

[changeset-bot]

🦋 Changeset detected

Latest commit: ba7668f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@tanstack/intent	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: a19fb345-d092-40e0-8e6c-d690603e38cc

📥 Commits

Reviewing files that changed from the base of the PR and between c16a6a8 and ba7668f.

📒 Files selected for processing (4)

• .changeset/validate-example-typecheck-reuse.md
• packages/intent/src/commands/validate.ts
• packages/intent/src/validate/blocks.ts
• packages/intent/tests/validate-blocks.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

intent validate now reuses workspace path mappings and parsed non-virtual TypeScript source files across checks. Virtual example files are still parsed for each check. A regression test verifies that repeated checks report findings for the current example.

Changes

Validation cache reuse

Layer / File(s)	Summary
Cache contract and reuse packages/intent/src/validate/blocks.ts	checkSkillBlocks accepts an optional cache for workspace paths and TypeScript source files. Non-virtual source files are reused; virtual example files are read and parsed per check.
Validation wiring and regression coverage packages/intent/src/commands/validate.ts, packages/intent/src/validate/blocks.ts, packages/intent/tests/validate-blocks.test.ts, .changeset/validate-example-typecheck-reuse.md	Validation checks share a cache across libraries and package groups. The regression test checks valid and invalid examples across repeated calls. A patch changeset describes the reuse change and states that validation results are unchanged.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Refactor

Merge Risk: ⚪ Minimal · up to ba766

The cache reuse is ready to merge after normal checks. No actionable merge-blocking issue was established.

Security Architecture Review

Security architecture risk: 🔵 Low · up to ba766

The cache remains local to one validation operation, and example code is still checked independently. No new executable entrypoint or increased privilege was identified. Residual risk comes from assuming workspace mappings and imported source files remain unchanged while the cache is reused.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The demonstrated exposure is shared dependency data influencing multiple library-example checks within one local validation operation. The new test helper is not a runtime entrypoint, and the existing CLI route does not gain additional authority through the cache.

Trust Boundaries and Controls

• observed — Skill content enters link checking and virtual TypeScript files. The compiler-API path consumes those files for diagnostics and deprecation analysis rather than executing the example statements. Virtual example content is explicitly excluded from the shared parsed-source cache.

Resilience and Maintainability Implications

• inferred — Fresh operation-local ownership limits cache contamination across runs. Reusing the cache across changed roots, compiler implementations, or dependency contents would exceed the context demonstrated by supported callers; no security-sensitive consumer of such reuse was established.

Hardening Proposals

• proposed — Make the single-root, compatible-compiler, stable-source lifetime explicit in the cache contract. If future callers extend its lifetime or share it across contexts, introduce identity checks and invalidation before permitting that reuse.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly summarizes the main change: reusing workspace paths and parsed files across example checks to improve performance.
Description check	✅ Passed	The description explains the change, motivation, implementation, TypeScript version limits, and reported performance results. It omits the template’s Checklist and Release Impact sections, but the cor…

Full details: Docstring Coverage

Explanation

Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit ba7668f

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:sherif,t...	✅ Succeeded	1m 8s	View ↗
nx run-many --targets=build	✅ Succeeded	3s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-10-04 17:16:10 UTC

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@tanstack/intent@312

commit: ba7668f

[codspeed]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing perf/validate-example-typecheck (ba7668f) with main (c16a6a8)}