refactor(cube-model): simplify pass over the exporter source (FR-044)

Collapse the mirrored join arms, share the YAML file framing and the grains
tail, derive the unmappable-dimension message from the dispatch sets, and make
four helpers with no outside importers module-private. No output byte changes:
the corpus, canonical golden and reference byte-identical tests are unchanged.

Author: dmealing

server/typescript/packages/codegen-ts/src/cube/build-cube-model.ts

@@ -39,6 +39,7 @@ import {
   resolveObjectRef,
   resolveTableName,
   resolveTableSchema,
+  stripPackage,
   type MetaData,
   type MetaDimension,
   type MetaField,
@@ -74,14 +75,15 @@ import {
   ERR_CUBE_UNMAPPABLE_DIMENSION,
   ERR_CUBE_UNMAPPABLE_JOIN,
   ERR_CUBE_UNMAPPABLE_REPORT,
+  ERR_CUBE_UNSUPPORTED_DIALECT,
 } from "./cube-errors.js";
 import {
+  defaultedRawMemberName,
   dimensionColumn,
   docOf,
   grainsOf,
   measureMembers,
   memberKey,
-  rawMeasureName,
   segmentSpec,
   type MemberContext,
 } from "./cube-members.js";
@@ -162,8 +164,7 @@ interface SpinePlan {
 
 /** Entity short names along a `@via` path, for messages. */
 function pathText(from: MetaObject, path: Path): string {
-  const short = (key: string): string => (key.includes("::") ? key.slice(key.lastIndexOf("::") + 2) : key);
-  return [from.name, ...path.map((s) => short(s.targetEntity))].join(" -> ");
+  return [from.name, ...path.map((s) => stripPackage(s.targetEntity))].join(" -> ");
 }
 
 interface CubeDraft {
@@ -200,7 +201,10 @@ interface CubeDraft {
 export function buildCubeModel(root: MetaRoot, options: CubeModelOptions): CubeModel {
   // CubeDialect admits only these; a caller outside the type system gets a refusal, not SQLite SQL.
   if (options.dialect !== "postgres" && options.dialect !== "mysql") {
-    throw new Error(`buildCubeModel: dialect '${String(options.dialect)}' is not a Cube data source this exporter writes (postgres, mysql).`);
+    throw new CubeModelError(
+      ERR_CUBE_UNSUPPORTED_DIALECT,
+      `dialect '${String(options.dialect)}' is not a Cube data source this exporter writes (postgres, mysql).`,
+    );
   }
   return new CubeModelBuilder(root, options).build();
 }
@@ -215,7 +219,7 @@ export function hasReportingVocabulary(obj: MetaObject): boolean {
 }
 
 function hopLabel(node: MetaData): string {
-  const kind = node.type === TYPE_IDENTITY ? "identity.reference" : `relationship.${node.subType}`;
+  const kind = node.type === TYPE_IDENTITY ? `${TYPE_IDENTITY}.${IDENTITY_SUBTYPE_REFERENCE}` : `${TYPE_RELATIONSHIP}.${node.subType}`;
   return `${kind} '${memberKey(node)}'`;
 }
 
@@ -275,7 +279,7 @@ class CubeModelBuilder {
     private readonly options: CubeModelOptions,
   ) {
     this.d = options.dialect;
-    this.mc = { root, dialect: options.dialect, extract: { columnNamingStrategy: options.columnNamingStrategy } };
+    this.mc = { root, dialect: this.d, extract: { columnNamingStrategy: options.columnNamingStrategy } };
   }
 
   build(): CubeModel {
@@ -871,8 +875,9 @@ class CubeModelBuilder {
     const needed = new Set<string>();
     const need = (m: MetaMeasure): void => {
       needed.add(m.name);
-      // ADR-0039: defaultValue() resolves, as measureMembers reads it.
-      if (!m.isRatio() && m.defaultValue() !== undefined) needed.add(rawMeasureName(m.name));
+      // The `<m>Raw` twin is earned by one rule, in `defaultedRawMemberName`, shared with measureMembers.
+      const raw = defaultedRawMemberName(m);
+      if (raw !== undefined) needed.add(raw);
     };
     for (const f of shape.fields) {
       const m = f.measure;
@@ -953,9 +958,9 @@ class CubeModelBuilder {
     const pairs = fkFields.map((fk, i) => {
       const fkCol = joinColumnFor(fkEntity, fk, this.mc.extract);
       const keyCol = joinColumnFor(keyEntity, keyFields[i]!, this.mc.extract);
-      return h.fkOnSelf
-        ? `${cubeColumn(fkCol, this.d, renderer)} = ${joinedColumn(h.joined.name, keyCol, this.d, renderer)}`
-        : `${cubeColumn(keyCol, this.d, renderer)} = ${joinedColumn(h.joined.name, fkCol, this.d, renderer)}`;
+      // One predicate shape, both directions: self's column left, the joined cube's column right.
+      const [selfCol, joinedCol]: [string, string] = h.fkOnSelf ? [fkCol, keyCol] : [keyCol, fkCol];
+      return `${cubeColumn(selfCol, this.d, renderer)} = ${joinedColumn(h.joined.name, joinedCol, this.d, renderer)}`;
     });
     return { name: h.joined.name, relationship: h.relationship, sql: pairs.join(" AND ") };
   }

server/typescript/packages/codegen-ts/src/cube/cube-members.ts

@@ -67,6 +67,12 @@ const STRING_SUBTYPES: ReadonlySet<string> = new Set([
   FIELD_SUBTYPE_INET,
 ]);
 
+// The subtypes `dimensionOfField` maps, in the order the refusal below lists them — derived from
+// the dispatch sets and checks, so the message cannot go stale when a mapping is added or removed.
+const MAPPED_DIMENSION_SUBTYPES: readonly string[] = [
+  ...STRING_SUBTYPES, ...NUMBER_SUBTYPES, FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIMESTAMP,
+];
+
 /** `<owner resolution key>.<name>`: a member's address, as `@of` and `@via` spell it. */
 export function memberKey(node: MetaData): string {
   const owner = node.parent;
@@ -133,8 +139,8 @@ export function dimensionColumn(
   throw new CubeModelError(
     ERR_CUBE_UNMAPPABLE_DIMENSION,
     `${where} reads ${read} (field.${field.subType}), and the exporter maps no Cube dimension type for ` +
-      `field.${field.subType}: it maps string, enum, uuid, time, uri, inet, int, long, double, float, decimal, ` +
-      `currency, boolean, date and timestamp. Group by a field of one of those subtypes, or remove the dimension.`,
+      `field.${field.subType}: it maps ${MAPPED_DIMENSION_SUBTYPES.slice(0, -1).join(", ")} and ` +
+      `${MAPPED_DIMENSION_SUBTYPES.at(-1)}. Group by a field of one of those subtypes, or remove the dimension.`,
   );
 }
 
@@ -143,6 +149,15 @@ export function rawMeasureName(measure: string): string {
   return `${measure}Raw`;
 }
 
+/**
+ * The `<m>Raw` twin a measure earns: only a non-ratio `measure.aggregate` with `@default` gets one.
+ * `measureMembers` emits under this name and the facts cube keeps it — one rule, two consumers.
+ */
+export function defaultedRawMemberName(m: MetaMeasure): string | undefined {
+  // ADR-0039: defaultValue() resolves, so a measure inherited through extends keeps its default.
+  return !m.isRatio() && m.defaultValue() !== undefined ? rawMeasureName(m.name) : undefined;
+}
+
 /**
  * One measure as Cube members. `raw` is present for a measure.aggregate with `@default`: it is
  * the Table D aggregate, `public: false`, under `<m>Raw`, and `measure` reads it through
@@ -173,7 +188,8 @@ export function measureMembers(entity: MetaObject, m: MetaMeasure, where: string
   }
   const aggregate = aggregateSpec(entity, m, where, mc);
   if (n === undefined) return { measure: { name: m.name, ...aggregate, ...docOf(m) } };
-  const raw = rawMeasureName(m.name);
+  // Past the ratio branch, this measure satisfies the helper's rule: its twin name exists.
+  const raw = defaultedRawMemberName(m)!;
   return {
     raw: { name: raw, ...aggregate, public: false },
     measure: { name: m.name, sql: withDefault(memberRef(raw), n), type: "number", ...docOf(m) },

server/typescript/packages/codegen-ts/src/cube/cube-model-spec.ts

@@ -10,6 +10,9 @@
 
 import type { TimeGrain } from "@metaobjectsdev/metadata";
 
+/** The generator's name, as diagnostics and the catalog print it — and the note in every emitted file's header. */
+export const CUBE_MODEL_GENERATOR_NAME = "cube-model";
+
 /** Cube's data sources this exporter writes SQL for (open question 3). */
 export type CubeDialect = "postgres" | "mysql";
 

server/typescript/packages/codegen-ts/src/cube/cube-reports.ts

@@ -34,7 +34,7 @@ export interface ReportContribution {
 }
 
 /** How many grouping columns a rollup has: its attribute dimensions plus its time dimensions. */
-export function rollupDimensionCount(rollup: CubeRollupSpec): number {
+function rollupDimensionCount(rollup: CubeRollupSpec): number {
   const times = rollup.timeDimensions !== undefined ? rollup.timeDimensions.length : rollup.timeDimension !== undefined ? 1 : 0;
   return rollup.dimensions.length + times;
 }
@@ -87,12 +87,12 @@ export function coarsestFirst(rollups: readonly CubeRollupSpec[]): CubeRollupSpe
 }
 
 /** `RecentPrograms` → `recentProgramsScope`: the segment a report's `@filter` becomes (Table G). */
-export function scopeSegmentName(reportName: string): string {
+function scopeSegmentName(reportName: string): string {
   return `${reportName.charAt(0).toLowerCase()}${reportName.slice(1)}Scope`;
 }
 
 /** True when a lowered clause compares against a relative date anywhere inside it. */
-export function hasRelativeDate(clause: ViewFilterClause | undefined): boolean {
+function hasRelativeDate(clause: ViewFilterClause | undefined): boolean {
   if (clause === undefined) return false;
   switch (clause.kind) {
     case "and":

server/typescript/packages/codegen-ts/src/cube/cube-template.ts

@@ -14,7 +14,7 @@
 //      inside one, so `endraw` there is plain text.
 
 /** `{{`, `{%` or `{#`: text holding one is raw-wrapped for Jinja. */
-export const JINJA_OPENER = /\{[{%#]/;
+const JINJA_OPENER = /\{[{%#]/;
 
 /** The word that would end a `{% raw %}` block early. */
 export const JINJA_RAW_END = "endraw";

server/typescript/packages/codegen-ts/src/cube/cube-yaml.ts

@@ -30,16 +30,18 @@
 
 import { GENERATED_HEADER } from "../constants.js";
 import { CubeModelError, ERR_CUBE_UNESCAPABLE_LITERAL } from "./cube-errors.js";
-import type {
-  CubeDimensionSpec,
-  CubeJoinSpec,
-  CubeMeasureSpec,
-  CubeRollupSpec,
-  CubeSegmentSpec,
-  CubeSpec,
-  CubeViewCubeSpec,
-  CubeViewIncludeSpec,
-  CubeViewSpec,
+import {
+  CUBE_MODEL_GENERATOR_NAME,
+  type CubeDimensionMeta,
+  type CubeDimensionSpec,
+  type CubeJoinSpec,
+  type CubeMeasureSpec,
+  type CubeRollupSpec,
+  type CubeSegmentSpec,
+  type CubeSpec,
+  type CubeViewCubeSpec,
+  type CubeViewIncludeSpec,
+  type CubeViewSpec,
 } from "./cube-model-spec.js";
 import { escapeCubeTemplate, jinjaSafe, JINJA_RAW_END } from "./cube-template.js";
 
@@ -48,9 +50,6 @@ const INDENT = "  ";
 /** A mapping or a list item as lines, relative to its own indent. */
 type Lines = string[];
 
-/** The text after the header, naming the generator that wrote the file. */
-const HEADER_NOTE = "cube-model";
-
 /** A member reference inside a rollup: the member on the cube the rollup belongs to. */
 function cubeRef(member: string): string {
   return `CUBE.${member}`;
@@ -145,12 +144,16 @@ function renderDimension(dimension: CubeDimensionSpec, cube: string): Lines {
   ];
   if (dimension.primaryKey !== undefined) out.push(`primary_key: ${dimension.primaryKey}`);
   out.push(...documentation(dimension, at));
-  if (dimension.meta !== undefined && dimension.meta.grains.length > 0) {
-    out.push("meta:", ...indented(flowList("grains", dimension.meta.grains)));
-  }
+  out.push(...grainsLines(dimension.meta));
   return out;
 }
 
+/** The `meta:` block, present only when the member carries grains (empty grains emit nothing). */
+function grainsLines(meta: CubeDimensionMeta | undefined): Lines {
+  if (meta === undefined || meta.grains.length === 0) return [];
+  return ["meta:", ...indented(flowList("grains", meta.grains))];
+}
+
 function renderMeasure(measure: CubeMeasureSpec, cube: string): Lines {
   const at = `cube '${cube}' measure '${measure.name}'`;
   const filters = (measure.filters ?? []).map((f): Lines => [`sql: ${sqlScalar(f.sql)}`]);
@@ -212,9 +215,7 @@ function renderViewInclude(include: CubeViewIncludeSpec, view: string): Lines {
   const out: Lines = [`name: ${nameScalar(include.name)}`];
   if (include.alias !== undefined) out.push(`alias: ${nameScalar(include.alias)}`);
   out.push(...documentation(include, at));
-  if (include.meta !== undefined && include.meta.grains.length > 0) {
-    out.push("meta:", ...indented(flowList("grains", include.meta.grains)));
-  }
+  out.push(...grainsLines(include.meta));
   return out;
 }
 
@@ -237,8 +238,7 @@ export function renderCubeViewYaml(view: CubeViewSpec): string {
     ...documentation(view, at),
     ...blockList("cubes", view.cubes.map((entry) => renderViewCube(entry, view.name))),
   ];
-  const lines = [`# ${GENERATED_HEADER} — ${HEADER_NOTE}`, "views:", ...indented(listItem(body))];
-  return `${lines.join("\n")}\n`;
+  return wrapFile("views:", body);
 }
 
 /**
@@ -247,6 +247,11 @@ export function renderCubeViewYaml(view: CubeViewSpec): string {
  * (it holds a Jinja opener) and holds `endraw`.
  */
 export function renderCubeYaml(cube: CubeSpec): string {
-  const lines = [`# ${GENERATED_HEADER} — ${HEADER_NOTE}`, "cubes:", ...indented(listItem(renderCube(cube)))];
+  return wrapFile("cubes:", renderCube(cube));
+}
+
+/** The framing both file kinds share: header line, one top-level key, its items indented, trailing newline. */
+function wrapFile(rootKey: string, item: Lines): string {
+  const lines = [`# ${GENERATED_HEADER} — ${CUBE_MODEL_GENERATOR_NAME}`, rootKey, ...indented(listItem(item))];
   return `${lines.join("\n")}\n`;
 }

server/typescript/packages/codegen-ts/src/generators/cube-model.ts

@@ -32,7 +32,13 @@ import { DEFAULT_COLUMN_NAMING_STRATEGY, type MetaObject } from "@metaobjectsdev
 import type { EmittedFile, GenContext, Generator } from "../generator.js";
 import { buildCubeModel, hasReportingVocabulary } from "../cube/build-cube-model.js";
 import { CubeModelError, ERR_CUBE_UNSUPPORTED_DIALECT } from "../cube/cube-errors.js";
-import { JOIN_PATH_SEPARATOR, type CubeDialect, type CubeModel, type CubeSpec } from "../cube/cube-model-spec.js";
+import {
+  CUBE_MODEL_GENERATOR_NAME,
+  JOIN_PATH_SEPARATOR,
+  type CubeDialect,
+  type CubeModel,
+  type CubeSpec,
+} from "../cube/cube-model-spec.js";
 import { renderCubeViewYaml, renderCubeYaml } from "../cube/cube-yaml.js";
 
 export interface CubeModelGeneratorOptions {
@@ -50,9 +56,6 @@ export interface CubeModelGeneratorOptions {
   readonly target?: string;
 }
 
-/** The generator's name, as diagnostics and the catalog print it. */
-export const CUBE_MODEL_GENERATOR_NAME = "cube-model";
-
 /** Where a cube's file lands, relative to the target's outDir (Table A). */
 const CUBE_FILE_DIR = "model/cubes";