feat(api-gateway): granularities config and /v1/granularities endpoint

[igorlukanin]

Summary

Engine-side foundation for configurable, deployment-wide granularities:

• New granularities shape on time dimensions. Accepts a dict { includes?, excludes?, custom? } alongside the legacy flat array. includes/excludes (string list or '*') select from the enabled set; custom defines per-dimension granularities. Mutually exclusive except for includes: '*' + excludes: [...].
• Deployment-wide granularities config. Configurable via CUBEJS_GRANULARITIES (comma-separated list), per-custom env vars CUBEJS_GRANULARITIES_<NAME>_INTERVAL|TITLE|OFFSET|ORIGIN, or config.granularities (list or context-dependent function). File config fully replaces env vars.
• GET /v1/granularities. New read-only endpoint returning the resolved set (built-ins + customs) for the request's security context.
• /v1/meta enrichment. Each time-dimension granularity now carries type ('built-in' / 'custom'), title, format (d3-time-format), and interval. Per-dimension includes/excludes are resolved against the deployment config so the response reflects the effective set.
• /v1/load + /v1/cubesql annotations. Same type/format enrichment flows through prepareAnnotation to query responses.
• Client SDK types widened. Granularity / GranularityAnnotation and the Rust transport struct in @cubejs-backend/native now carry type and format.

Out of scope (separate follow-ups):

• allow_no_granularity parameter end-to-end
• XMLA / DAX exposure of custom granularities
• Elasticsearch + MS Fabric driver SQL for custom granularities
• AI Engineer prompts
• Documentation, telemetry, release notes

Test plan

• Added unit tests covering every row of the new resolution table (granularities-shape.test.ts) and global config precedence (granularities-config.test.ts).
• Extended cube-validator.test.ts for the new dict shape: includes/excludes mutual-exclusion, built-in shadowing, legacy form acceptance.
• Extended prepare-annotation.test.ts for the new type / format fields on the granularity annotation.
• Existing pre-agg matching tests still pass (no hash-affecting changes).
• Manual end-to-end against a Postgres scratch model:
  • /v1/granularities returns 8 built-ins + customs sourced from CUBEJS_GRANULARITIES.
  • /v1/meta for a time dim with granularities: { includes: ['year', 'quarter'], custom: [...] } returns exactly those built-ins plus the local custom; a dim with the legacy flat array gets all enabled built-ins plus its locals.
  • /v1/load with granularity: 'week' returns { type: 'built-in', title: 'Week', interval: '1 week', format: '%b %-d, %Y' }.
• CI: lint + tsc + unit + integration.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.53%. Comparing base (9268376) to head (f83bbd6).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #10918      +/-   ##
==========================================
+ Coverage   78.93%   83.53%   +4.59%     
==========================================
  Files         470      254     -216     
  Lines       92868    75869   -16999     
  Branches     3450        0    -3450     
==========================================
- Hits        73307    63377    -9930     
+ Misses      19056    12492    -6564     
+ Partials      505        0     -505     

Flag	Coverage Δ
cube-backend	?
cubesql	83.53% <ø> (+<0.01%)	⬆️

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.