[paustint]

Parses FORMULA('field + field' | 'field - field') in WHERE into a typed AST, validated against Salesforce's supported grammar and reconstructed by the composer/formatter. Verified against a live Salesforce org.

Closes #298

[Copilot]

🟢 Approval recommended

The implementation is consistent across lexer/parser/composer/public API, and the added tests and docs align with the described WHERE-only, +/--only grammar support.

Pull request overview

Adds first-class support for Salesforce’s FORMULA() arithmetic conditions in WHERE clauses by parsing the quoted arithmetic into a typed nested AST, validating the supported grammar, and ensuring both the composer and formatter can reconstruct canonical output.

Changes:

• Introduces a dedicated FORMULA lexer token and WHERE-only parser support that builds a FormulaFunctionExp with a nested FormulaBinaryExpression.
• Updates composing/formatting to render FORMULA() from the nested AST (not raw source text) and exposes an isFormulaFunction public type guard.
• Expands test coverage (valid/invalid cases, lexer token behavior, ignoreParseErrors behavior) and updates README/docs/examples and changelog.

File summaries

File	Description
test/test-cases.ts	Adds parsed-AST expectations for FORMULA() comparisons in WHERE.
test/test-cases-for-is-valid.ts	Adds validity matrix covering allowed/forbidden FORMULA() placements and shapes.
test/lexer.spec.ts	Verifies FORMULA is tokenized as a dedicated, case-insensitive function token.
test/formula.spec.ts	New focused test suite for parsing, composing, formatting, and exported type guard behavior.
src/utils.ts	Adds isFormulaFunction type guard for FormulaFunctionExp.
src/parser/parser.ts	Implements FORMULA() parsing in WHERE, constrains operators/values, and threads allow/deny through clause parsing.
src/parser/lexer.ts	Adds TokenKind.FORMULA and keyword mapping / identifier-likeness.
src/parser/formula.ts	New parser helper that validates and parses the quoted arithmetic expression into a typed AST.
src/composer/leaf.ts	Updates function rendering to compose FORMULA() from nested AST.
src/api/public-utils.ts	Re-exports isFormulaFunction as part of the public utility API.
src/api/api-models.ts	Adds Formula* AST model types and extends ValueFunctionCondition.fn to include them.
README.md	Documents FORMULA() support, constraints, and example AST shape; updates utility list.
docs/static/sample-queries-json.json	Adds sample queries demonstrating FORMULA() usage.
docs/docs/overview.md	Adds overview documentation and example output for FORMULA() in WHERE.
docs/docs/api.md	Documents the new isFormulaFunction helper.
CHANGELOG.md	Adds an [Unreleased] entry under ### Added describing the new feature.

Review details

• Files reviewed: 16/16 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The feature implementation aligns with the stated constraints and is backed by targeted lexer/parser/composer tests, with only a minor comment-doc mismatch noted.

Review details

• Files reviewed: 16/16 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The implementation is narrowly scoped, includes validation to match the documented grammar constraints, and is backed by targeted unit tests plus documentation and changelog updates.

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The implementation enforces the documented Salesforce grammar constraints and is backed by targeted lexer/parser/composer tests plus corresponding documentation updates.

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 0 new
• Review effort level: Lite