Describe sort-argument misuse in index field lists

[Sanjays2402]

Fixes #30270.

@@index([created_at(sort: Desc)]) failed during contract resolution with the cryptic PSL_INVALID_ATTRIBUTE_SYNTAX / "Expected a field name". The field-list parser (fieldRef) only accepts bare IdentifierAst tokens, while a sort annotation parses as a FunctionCallAst — so users got a message that described the parser's expectation rather than their mistake.

parseFieldName now detects the function-call shape and reports the actual problem: Expected a bare field name, but found "created_at(...)" — field lists do not accept arguments, so (sort: Asc/Desc) is not supported here. Anything that isn't a single-segment call keeps the original "Expected a field name" diagnostic. (Full sort-direction support would need index-IR/DDL changes; the issue accepts the descriptive diagnostic.)

Testing: new unit test in psl-parser fails before the fix (message lacks any mention of sort) and passes after; new end-to-end test in contract-psl reproduces the issue's exact @@index([createdAt(sort: Desc)]) schema and asserts the diagnostic names sort instead of the cryptic message. Full suites pass: psl-parser 703/703, contract-psl 463/463; tsc --noEmit and biome check clean on all touched files.

Summary by CodeRabbit

• Bug Fixes
  • Improved diagnostics for invalid sort annotations in field lists, including messages that identify the unsupported syntax.
  • Invalid usages such as id(sort: Desc) and index field lists with sort annotations now report the appropriate syntax error instead of a generic field-name error.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Advanced

Run ID: f2a95601-3d81-44f5-b639-749d10d0454e

📥 Commits

Reviewing files that changed from the base of the PR and between b734ad9 and b992e62.

📒 Files selected for processing (3)

• packages/1-framework/2-authoring/psl-parser/src/attribute-spec/combinators/field-ref.ts
• packages/1-framework/2-authoring/psl-parser/test/attribute-spec-combinators.test.ts
• packages/2-sql/2-authoring/contract-psl/test/interpreter.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The parser now gives a specific diagnostic when a field list contains a function-call argument. Tests cover direct field-reference parsing and @@index interpretation with sort annotations.

Changes

Field-list diagnostic clarification

Layer / File(s)	Summary
Field reference diagnostic packages/1-framework/2-authoring/psl-parser/src/attribute-spec/combinators/field-ref.ts	The parser inspects non-identifier arguments and reports a message that names single-path function calls and explains that field lists do not accept arguments.
Diagnostic validation packages/1-framework/2-authoring/psl-parser/test/attribute-spec-combinators.test.ts, packages/2-sql/2-authoring/contract-psl/test/interpreter.test.ts	Tests verify that sort annotations produce PSL_INVALID_ATTRIBUTE_SYNTAX diagnostics that mention sort instead of returning only Expected a field name.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: wmadden-electric

Merge Risk: ⚪ Minimal · up to b992e

The change clarifies unsupported field-list diagnostics and adds matching parser and interpreter coverage, with no established merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: improving diagnostics for unsupported sort arguments in index field lists.
Linked Issues check	✅ Passed	Issue #30270 allows either support for sort annotations or a descriptive diagnostic when sort annotations are unsupported. field-ref.ts detects single-path function calls and reports that field list…
Out of Scope Changes check	✅ Passed	The changes are limited to the field-name diagnostic and two tests for the parser and SQL contract interpreter. These changes directly support issue #30270 and do not add unrelated behavior.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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