feat: add format description handling

[vasilev-alex]

No description provided.

[claude]

Claude finished @vasilev-alex's task in 2m 40s —— View job

---

Code Review: feat: add format description handling

• Gather context and read changed files
• Review code quality and best practices
• Review security considerations
• Review performance considerations
• Review test coverage
• Provide final review summary

---

Summary

This PR adds a formatDescription field to query annotations, resolving format metadata (name + d3-format specifier + optional currency) so that clients receive a consistent, pre-resolved format descriptor alongside the raw format field. The approach is clean and well-structured — the resolveFormatDescription function, constant maps, and test coverage are all solid foundations.

I've left 6 inline comments on specific issues. Here's a high-level overview:

Issues to Address

1. Bug: Missing abbr and accounting standard formats (High)
STANDARD_FORMAT_SPECIFIERS only maps percent, currency, and number, but the codebase supports abbr and accounting as valid format values (confirmed in schema compiler tests and the client-side FormatDescriptionBaseName type). These will silently fall back to the number default. See inline comment →

2. Non-numeric formats get a misleading number default (Medium)
Dimensions with format: 'imageUrl', 'link', 'id', or { type: 'custom-time' } all fall through to { name: 'number', specifier: ',.2f' }. This is semantically incorrect and could mislead consumers into applying numeric formatting to non-numeric values. Consider returning undefined for non-numeric formats. See inline comment →

3. Type divergence between server and client (Medium)
The server-side FormatDescription type uses name: string while the client-side uses a strict union type FormatDescriptionName. These represent the same concept but will drift apart over time. Consider sharing the type or aligning them. See inline comment →

Suggestions

4. Use stricter typing for format parameter (Low)
resolveFormatDescription accepts format: any — using the existing DimensionFormat | MeasureFormat union would improve type safety. See inline comment →

5. Unrelated package.json description change (Nit)
The "Cube.js" → "Cube" rename is cosmetic and unrelated to the feature. See inline comment →

What Looks Good

• Well-structured function: resolveFormatDescription is clean, readable, and follows a clear priority order (custom-numeric → standard string → default)
• Good test coverage: 8 new test cases covering standard formats, custom-numeric with/without alias, currency propagation, and default fallbacks
• Client types are well-documented: The FormatDescription type in types.ts has clear JSDoc comments with d3-format references
• No security concerns: No user input flows unsanitized, no injection vectors
• No performance concerns: The resolution is a simple map lookup with negligible overhead
• Empty index.d.ts cleanup: Removing the 0-byte file is fine

Test Coverage Gaps

Consider adding tests for:

• format: 'imageUrl' / format: 'link' / format: { type: 'custom-time', ... } — to document the expected behavior for non-numeric formats
• format: 'abbr' / format: 'accounting' — once these are added to STANDARD_FORMAT_SPECIFIERS
• Currency without a currency format (e.g., format: 'number' with currency: 'USD') — to verify currency is still attached

---

[codecov]

Codecov Report

❌ Patch coverage is 95.65217% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 58.07%. Comparing base (43b3fd5) to head (759f518).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
...ema-compiler/src/compiler/CubeToMetaTransformer.ts	95.23%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #10688      +/-   ##
==========================================
+ Coverage   58.01%   58.07%   +0.05%     
==========================================
  Files         215      215              
  Lines       16648    16669      +21     
  Branches     3347     3354       +7     
==========================================
+ Hits         9659     9681      +22     
+ Misses       6499     6498       -1     
  Partials      490      490              

Flag	Coverage Δ
cube-backend	58.07% <95.65%> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.