perf(core): cache parsed ASTs in the expression engine

[SingleSourceStudios]

Issue #46, Candidate 2 (PR 3 of 4). Follows the __perf__ scaffold (#53) and the compiler fix (#87).

Summary

evaluate(template, context) ran extractExpression -> tokenize -> parse on every call. The engine is pure (no eval/Function, and evaluateNode never mutates the AST), so a parsed AST is valid forever and safe to share. In a long-running spec where the same quality gate, invariant, branch condition, or verification check fires repeatedly, the tokenize/parse work compounds.

• Module-level Map<string, ASTNode> keyed on the raw template string, 1000-entry soft cap, LRU eviction via Map insertion order (a hit re-inserts the key; eviction drops the oldest).
• Only successful parses are cached; a malformed template re-throws on every call exactly as before.
• evaluateNode still runs per call against the live context, so results remain per-context.
• clearExpressionCache(), expressionCacheSize(), expressionCacheHas() exported for test isolation and diagnostics (pure reads).

Behaviour-preserving

Cached and uncached evaluations are identical, distinct templates never collide, and eviction at the cap re-parses without corrupting results.

Tests (packages/core/expression.test.ts)

• Cache-hit equivalence: same template, different contexts, correct per-context results.
• No cross-template collision (interleaved distinct templates).
• Cap-bounded eviction (fill cap+50, size stays 1000).
• Correct re-evaluation of an evicted template.
• LRU-vs-FIFO discriminator: a hot (recently-used) template survives eviction while the least-recently-used victim is dropped. Verified to fail under a FIFO implementation, so it genuinely pins LRU rather than just cap behaviour.

Proof (npm run bench, Candidate-2 assertion: evaluate the same expression 10,000x)

	best of 5	margin vs 1000ms threshold
before (main)	~13.2ms	~75x
after (this PR)	~1.46ms	~685x

~9x faster; the assertion passes with a far wider margin. Thresholds left unchanged per the issue's calibration guidance.

Scope

packages/core/expression.ts + its tests only. index.ts deliberately untouched; the new diagnostics are imported directly from ./expression.js by the test.

Test Plan

• npm run build:core && npm run build
• npm test (503 passed)
• npm run typecheck
• npm run lint (no new errors; 5 pre-existing out-of-scope errors unchanged)
• node spec/fixtures/run-fixtures.mjs (29 passed)
• npm run bench (3 passed, Candidate-2 margin widened)

🤖 Generated with Claude Code

---

Summary by cubic

Caches parsed ASTs in the expression engine to skip re-tokenizing/parsing on repeat evaluations. Results are identical; the 10k-evals bench is ~9x faster (13.2ms → 1.46ms), meeting the goals of issue #46.

• New Features
  • Module-level Map<string, ASTNode> cache keyed by raw template; 1000-entry soft cap with LRU eviction.
  • Only successful parses are cached; malformed templates still throw on each call.
  • evaluateNode runs per call, so results stay per-context.
  • Exported clearExpressionCache, expressionCacheSize, and expressionCacheHas for tests and diagnostics.

^{Written for commit 3d7f62c. Summary will update on new commits. Review in cubic}

[coderabbitai]

Warning

Review limit reached

@SingleSourceStudios, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 17 minutes and 5 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b7d88d05-8eac-46cd-b48e-e470520223cf

📥 Commits

Reviewing files that changed from the base of the PR and between 086e8b5 and 3d7f62c.

📒 Files selected for processing (2)

• packages/core/expression.test.ts
• packages/core/expression.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/expression-ast-cache

---

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 and usage tips.}

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}