@metaobjectsdev/metadata 1.0.13 → 1.1.0

package/src/core/reporting/report-describe.ts

@@ -0,0 +1,206 @@
+// The reporting vocabulary in words (FR-044): what a dimension groups by, what a measure
+// computes, which rows a segment or report is scoped to, and why a report is not served.
+//
+// One home for the wording. The docs generators print these sentences on the markdown model pages
+// (codegen-ts) and on the HTML site (docs-site); both read them from here, so the two
+// surfaces cannot say different things about the same node.
+//
+// Every function returns PLAIN TEXT whose identifiers sit in single-backtick spans
+// ("sum of `Invoice.amountCents` where segment `paid`"). A caller turns the spans into
+// its own markup. Nothing here derives SQL: a description says what a column means, never
+// how the view computes it.
+//
+// Browser-safe: no Node-only import.
+
+import type { MetaData } from "../../shared/meta-data.js";
+import type { MetaRoot } from "../../shared/meta-root.js";
+import { TYPE_DIMENSION, TYPE_MEASURE, TYPE_SEGMENT } from "../../shared/base-types.js";
+import { AGG_ALL } from "../../persistence/origin/origin-constants.js";
+import type { MetaObject } from "../object/meta-object.js";
+import { OBJECT_REPORT_ATTR_FILTER, OBJECT_REPORT_ATTR_SEGMENT, OBJECT_REPORT_ATTR_SPINE } from "../object/object-constants.js";
+import {
+  DIMENSION_SUBTYPE_TIME,
+  MEASURE_SUBTYPE_RATIO,
+  REPORTING_ATTR_AGG,
+  REPORTING_ATTR_DEFAULT,
+  REPORTING_ATTR_DENOMINATOR,
+  REPORTING_ATTR_DISTINCT,
+  REPORTING_ATTR_FILTER,
+  REPORTING_ATTR_GRAINS,
+  REPORTING_ATTR_NUMERATOR,
+  REPORTING_ATTR_OF,
+  REPORTING_ATTR_SEGMENT,
+  REPORTING_ATTR_VIA,
+} from "./reporting-constants.js";
+import { reportSpine } from "./report-accessors.js";
+import { reportReadSource } from "./report-read-model.js";
+import { reportSpineEntity, type ReportField, type ReportShape } from "./report-shape.js";
+
+/** Inline code. A backtick cannot sit inside a single-backtick span, so it is dropped. */
+function tick(text: string): string {
+  return `\`${text.replace(/`/g, "")}\``;
+}
+
+function stringList(v: unknown): string[] {
+  if (Array.isArray(v)) return v.filter((x): x is string => typeof x === "string");
+  return typeof v === "string" ? [v] : [];
+}
+
+/** A row-scope filter as the loader holds it: compact JSON in declared order, in a code span. */
+export function describeFilter(filter: unknown): string {
+  return tick(JSON.stringify(filter ?? {}));
+}
+
+/**
+ * "segment `paid` and filter `{…}`": the rows a measure or a report is scoped to, or
+ * undefined when it declares neither. The two combine by AND, as the lowering combines them.
+ */
+export function describeRowScope(segment: unknown, filter: unknown): string | undefined {
+  const parts: string[] = [];
+  if (typeof segment === "string" && segment !== "") parts.push(`segment ${tick(segment)}`);
+  if (filter !== undefined && filter !== null) parts.push(`filter ${describeFilter(filter)}`);
+  return parts.length > 0 ? parts.join(" and ") : undefined;
+}
+
+/** "`Program.title` via `Purchase.program`": the column a dimension groups by. */
+function dimensionColumn(dim: MetaData): string {
+  // ADR-0039: resolving reads, here and in every describer below, so a node that
+  // `extends` another is described by its effective attributes. References are
+  // printed as the author wrote them (ADR-0059), not as the loader resolved them.
+  const of = dim.authoredAttr(REPORTING_ATTR_OF);
+  const via = dim.authoredAttr(REPORTING_ATTR_VIA);
+  const column = tick(typeof of === "string" ? of : "");
+  return typeof via === "string" && via !== "" ? `${column} via ${tick(via)}` : column;
+}
+
+/** A dimension as its entity declares it: the column, and for a time dimension its grains. */
+export function describeDimension(dim: MetaData): string {
+  const column = dimensionColumn(dim);
+  if (dim.subType !== DIMENSION_SUBTYPE_TIME) return column;
+  return `${column}; grains: ${stringList(dim.attr(REPORTING_ATTR_GRAINS)).join(", ")}`;
+}
+
+/**
+ * A dimension as ONE report column. A time dimension is truncated to the grain the report
+ * picked; reports are UTC only (there is no time-zone vocabulary). After a `via` clause
+ * the truncation is set off by a comma, so it reads as applying to the column and not to
+ * the relationship path.
+ */
+export function describeDimensionColumn(dim: MetaData, grain?: string): string {
+  const column = dimensionColumn(dim);
+  if (grain === undefined || grain === "") return column;
+  const joiner = column.includes(" via ") ? "," : "";
+  return `${column}${joiner} truncated to ${grain}, UTC`;
+}
+
+/**
+ * "; `0` when there is nothing to aggregate": the clause a measure's `@default` adds (R9), or
+ * "" when it declares none. The declared integer is printed as written.
+ */
+function defaultClause(measure: MetaData): string {
+  const declared = measure.attr(REPORTING_ATTR_DEFAULT);
+  return typeof declared === "number" ? `; ${tick(String(declared))} when there is nothing to aggregate` : "";
+}
+
+/**
+ * A measure in words: the aggregate and its row scope, or the ratio and its null rule. A
+ * `@default` ends either with the value it reads when there is nothing to aggregate; a
+ * defaulted ratio is never null, so its null rule gives way to that clause.
+ */
+export function describeMeasure(measure: MetaData): string {
+  const fallback = defaultClause(measure);
+  if (measure.subType === MEASURE_SUBTYPE_RATIO) {
+    const numerator = measure.attr(REPORTING_ATTR_NUMERATOR);
+    const denominator = measure.attr(REPORTING_ATTR_DENOMINATOR);
+    const quotient = `${tick(String(numerator ?? ""))} / ${tick(String(denominator ?? ""))}`;
+    return fallback !== "" ? `${quotient}${fallback}` : `${quotient}, null when the denominator is 0`;
+  }
+  const columns = stringList(measure.authoredAttr(REPORTING_ATTR_OF)).map(tick);
+  const scope = describeRowScope(measure.attr(REPORTING_ATTR_SEGMENT), measure.attr(REPORTING_ATTR_FILTER));
+  if (columns.length === 0) {
+    // @agg any / all with no @of (loader rule M0): the row condition is the quantified predicate.
+    const quantifier = measure.attr(REPORTING_ATTR_AGG) === AGG_ALL ? "every row" : "some row";
+    return `true when ${quantifier} has ${scope ?? ""}${fallback}`;
+  }
+  const of = columns.length === 1 ? columns[0]! : `(${columns.join(", ")})`;
+  const distinct = measure.attr(REPORTING_ATTR_DISTINCT) === true ? "distinct " : "";
+  return `${String(measure.attr(REPORTING_ATTR_AGG) ?? "")} of ${distinct}${of}${scope !== undefined ? ` where ${scope}` : ""}${fallback}`;
+}
+
+/** A segment in words: its filter. */
+export function describeSegment(segment: MetaData): string {
+  return describeFilter(segment.attr(REPORTING_ATTR_FILTER));
+}
+
+/** One derived report column's definition, from the dimension or measure it comes from. */
+export function describeReportField(field: ReportField): string {
+  if (field.dimension !== undefined) return describeDimensionColumn(field.dimension, field.grain);
+  return field.measure !== undefined ? describeMeasure(field.measure) : "";
+}
+
+/**
+ * Where a report with `@spine` takes its rows (R8): "one row per distinct dimension tuple
+ * among the rows of `Program`, reached by `Purchase.program`, including those no `Purchase`
+ * refers to". Undefined for a report without `@spine`, whose rows are the groups of its
+ * `@from` rows and need no sentence. The spine is printed as declared.
+ */
+export function describeReportRows(shape: ReportShape, root: MetaRoot): string | undefined {
+  const entity = reportSpineEntity(shape.report, shape.from, root);
+  // Printed as the author wrote it (ADR-0059).
+  const authored = reportSpine(shape.report) !== undefined ? shape.report.authoredAttr(OBJECT_REPORT_ATTR_SPINE) : undefined;
+  const spine = typeof authored === "string" ? authored : undefined;
+  if (spine === undefined || entity === undefined) return undefined;
+  return (
+    `one row per distinct dimension tuple among the rows of ${tick(entity.name)}, reached by ${tick(spine)}, ` +
+    `including those no ${tick(shape.from.name)} refers to`
+  );
+}
+
+/**
+ * A report's row scope ({@link describeRowScope} over its `@segment` and `@filter`), or
+ * undefined when it declares neither. Under `@spine` the scope chooses which rows of `@from`
+ * are aggregated and never removes a row of the report, so it reads "aggregating only
+ * segment `paid`".
+ */
+export function describeReportRowScope(report: MetaObject): string | undefined {
+  // ADR-0039: resolving.
+  const scope = describeRowScope(report.attr(OBJECT_REPORT_ATTR_SEGMENT), report.attr(OBJECT_REPORT_ATTR_FILTER));
+  if (scope === undefined) return undefined;
+  return reportSpine(report) !== undefined ? `aggregating only ${scope}` : scope;
+}
+
+/** The neutral logical type of a derived column: its Table B subtype, `[]` for an array. */
+export function reportFieldTypeName(field: ReportField): string {
+  // ADR-0039: resolvedIsArray() is the resolving read of the native array flag.
+  return field.typeSource?.resolvedIsArray() === true ? `${field.subType}[]` : field.subType;
+}
+
+/**
+ * Why a report is not served, or undefined when it is. The loader refuses an abstract
+ * report (R11) and a read source whose `@kind` is not `view` (R10), so the one way a loaded
+ * report goes unserved is declaring no read source at all (Plan 3 Table A).
+ */
+export function reportNotServedReason(report: MetaObject): string | undefined {
+  return reportReadSource(report) === undefined ? "Not served: declares no view source" : undefined;
+}
+
+const DIMENSION_ATTRS = [REPORTING_ATTR_OF, REPORTING_ATTR_VIA] as const;
+const TIME_DIMENSION_ATTRS = [...DIMENSION_ATTRS, REPORTING_ATTR_GRAINS] as const;
+const AGGREGATE_ATTRS = [
+  REPORTING_ATTR_AGG, REPORTING_ATTR_OF, REPORTING_ATTR_DISTINCT, REPORTING_ATTR_SEGMENT, REPORTING_ATTR_FILTER,
+  REPORTING_ATTR_DEFAULT,
+] as const;
+const RATIO_ATTRS = [REPORTING_ATTR_NUMERATOR, REPORTING_ATTR_DENOMINATOR, REPORTING_ATTR_DEFAULT] as const;
+const SEGMENT_ATTRS = [REPORTING_ATTR_FILTER] as const;
+
+/**
+ * The attributes the describer for `node` reads, so a documentation coverage audit can
+ * mark exactly those as rendered and no others. Kept beside the describers: a describer
+ * that starts reading a new attribute adds it here. Empty for any other node.
+ */
+export function reportingDescribedAttrs(node: MetaData): readonly string[] {
+  if (node.type === TYPE_DIMENSION) return node.subType === DIMENSION_SUBTYPE_TIME ? TIME_DIMENSION_ATTRS : DIMENSION_ATTRS;
+  if (node.type === TYPE_MEASURE) return node.subType === MEASURE_SUBTYPE_RATIO ? RATIO_ATTRS : AGGREGATE_ATTRS;
+  if (node.type === TYPE_SEGMENT) return SEGMENT_ATTRS;
+  return [];
+}

package/src/core/reporting/report-read-model.ts

@@ -0,0 +1,177 @@
+// A report's READ MODEL (FR-044): a detached object carrying one real `field.*`
+// child per derived field (Table B) and a copy of the report's own read-only source.
+//
+// WHY IT EXISTS
+//
+// An `object.report` declares no fields: its read shape is derived from its
+// dimensions and measures. A metadata-driven runtime walks an object's field
+// children in a dozen places (column list, filter and sort resolution, the name
+// map, every read coercion). Rather than teach each of them what a report is, the
+// runtime reads a report through this model and sees ordinary fields.
+//
+// WHY IT IS DETACHED
+//
+// The model is never added to the root: it has no parent, `root.objects()` does
+// not list it, and the canonical serializer, `fmt`, codegen and every other tree
+// walker never see it. Nothing in the loaded tree is mutated to build it; in
+// particular the report's own source node is COPIED, not re-parented
+// (`addChild` rewrites the child's parent). The nodes are constructed directly,
+// not through the registry, so the sealed registry is not involved and no
+// vocabulary is added: every node is an already-registered `type.subType`.
+//
+// It keeps the report's name, package and `object.report` subtype, so a consumer
+// holding it can still tell it is a report (no identity, read-only).
+
+import { TypeId } from "../../registry.js";
+import { TYPE_FIELD } from "../../shared/base-types.js";
+import type { MetaRoot } from "../../shared/meta-root.js";
+import { isReadOnlySource } from "../../shared/node-guards.js";
+import { MetaSource } from "../../persistence/source/meta-source.js";
+import { SOURCE_ATTR_ROLE, SOURCE_ROLE_PRIMARY } from "../../persistence/source/source-constants.js";
+import { FIELD_ATTR_DB_COLUMN_TYPE, FIELD_ATTR_LOCAL_TIME } from "../../persistence/db/db-constants.js";
+import { MetaObject } from "../object/meta-object.js";
+import { MetaField } from "../field/meta-field.js";
+import {
+  FIELD_ATTR_CURRENCY,
+  FIELD_ATTR_FILTERABLE,
+  FIELD_ATTR_INT_VALUE_MAP,
+  FIELD_ATTR_MAX_LENGTH,
+  FIELD_ATTR_PRECISION,
+  FIELD_ATTR_REQUIRED,
+  FIELD_ATTR_SCALE,
+  FIELD_ATTR_STORAGE,
+  FIELD_ATTR_VALUES,
+  FIELD_SUBTYPE_MAP,
+} from "../field/field-constants.js";
+import { opsForField } from "../query/query-constants.js";
+import { reportShape, type ReportField } from "./report-shape.js";
+
+/**
+ * Table B: the type-shaping attrs a derived field carries from its `typeSource`,
+ * read with the RESOLVING accessor (ADR-0039) so a value the `@of` field inherits
+ * through `extends` is carried too. `@dbColumnType` and `isArray` are handled
+ * separately below. Nothing else is carried: no `@column`, `@required`,
+ * `@default`, validators or views.
+ */
+const CARRIED_ATTRS = [
+  FIELD_ATTR_CURRENCY,
+  FIELD_ATTR_VALUES,
+  FIELD_ATTR_INT_VALUE_MAP,
+  FIELD_ATTR_MAX_LENGTH,
+  FIELD_ATTR_PRECISION,
+  FIELD_ATTR_SCALE,
+  FIELD_ATTR_LOCAL_TIME,
+  FIELD_ATTR_STORAGE,
+] as const;
+
+/** True for a derived field whose source field is an array or a `field.map`. */
+function isArrayOrMap(field: MetaField): boolean {
+  return field.resolvedIsArray() || field.subType === FIELD_SUBTYPE_MAP;
+}
+
+function derivedField(f: ReportField): MetaField {
+  const field = new MetaField(new TypeId(TYPE_FIELD, f.subType), f.name);
+  // From the derived shape, never from the type source: a `min` of a required column
+  // is still nullable, and a dimension reached by `@via` is nullable.
+  field.setAttr(FIELD_ATTR_REQUIRED, f.required);
+  const src = f.typeSource;
+  if (src !== undefined) {
+    for (const name of CARRIED_ATTRS) {
+      const value = src.attr(name);
+      if (value !== undefined) field.setAttr(name, value);
+    }
+    // ADR-0039: own — `@dbColumnType` is the one deliberately own-only attr (a
+    // physical column-type override is never inherited), and every consumer reads
+    // it with `ownAttr`. So it is read own from the type source and set OWN here:
+    // the derived field carries exactly what the `@of` field itself declares, and
+    // nothing its supers declare. A field that `extends` another does not get the
+    // parent's `@dbColumnType` either, so this matches how a projection field
+    // would see it.
+    const dbColumnType = src.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
+    if (dbColumnType !== undefined) field.setAttr(FIELD_ATTR_DB_COLUMN_TYPE, dbColumnType);
+    // `isArray` is a native flag, not an attr; resolvedIsArray() is its resolving read.
+    if (src.resolvedIsArray()) field.setIsArray(true);
+  }
+  // Table C (Plan 3): a report author has no node to put @filterable on, so every
+  // derived field that has a filter band is filterable, and (the sort allowlist follows
+  // `@filterable`) sortable. Set on this detached model only; no vocabulary is added and the
+  // declared tree is not touched. EXCEPT an array or a map: an array column cannot be compared
+  // with a scalar (`text[] = text` is a Postgres error), and the entity rule already refuses
+  // `@filterable` on an array field, so a derived field whose source is either is neither
+  // filterable nor sortable, in every port.
+  if (!isArrayOrMap(field) && opsForField(field).length > 0) field.setAttr(FIELD_ATTR_FILTERABLE, true);
+  return field;
+}
+
+/**
+ * The source a report is READ from: its own read-only source with `@role: primary`,
+ * else its first own read-only source. Undefined when it declares none (Table A:
+ * not lowered, not served).
+ *
+ * This is the rule that NAMES the lowered view — `viewName` / `projectionViewSource`
+ * in codegen-ts's `projection/extract-view-spec.ts`, reached for a report through
+ * `projectionViewName`. It is restated here because the metadata package cannot
+ * depend on a codegen package; the two must stay the same rule, or the runtime
+ * reads a relation the lowering did not create.
+ *
+ * What the loader permits, measured: a report may declare several read-only sources
+ * (a `@role: replica` view beside its primary view loads clean, in either order);
+ * `@role` defaults to `primary`; a report whose sources include no primary is
+ * `ERR_SOURCE_NO_PRIMARY` and a writable source on a report is refused. So for every
+ * model that loads, the primary branch fires. The first-read-only fallback covers a
+ * tree built in code, and keeps this rule identical to the lowering's.
+ */
+export function reportReadSource(report: MetaObject): MetaSource | undefined {
+  // ADR-0039: own — source classification reads the sources the report declares
+  // ITSELF, exactly as the lowering's `viewName` does.
+  const readOnly = report.ownChildren().filter(isReadOnlySource);
+  return readOnly.find((s) => s.role === SOURCE_ROLE_PRIMARY) ?? readOnly[0];
+}
+
+/**
+ * A detached copy of a source node: same `type.subType`, name and effective attrs,
+ * and nothing else (attrs only — the loaded node is never re-parented).
+ *
+ * The copy is the model's ONLY source, and it is pinned to `@role: primary`: the
+ * runtime resolves an object's table through `primaryRdbSource`, which considers
+ * primary sources only, so this is what makes the read land on the selected
+ * source's physical name rather than on a default table name nobody declared.
+ */
+function copySource(source: MetaSource): MetaSource {
+  const copy = new MetaSource(source.typeId, source.name);
+  // ADR-0039: resolving — the copy carries the source's effective configuration
+  // (@kind, the physical-name alias, @schema, @unmanaged, @sql).
+  for (const [name, value] of source.attrs()) copy.setAttr(name, value);
+  copy.setAttr(SOURCE_ATTR_ROLE, SOURCE_ROLE_PRIMARY);
+  return copy;
+}
+
+const READ_MODELS = new WeakMap<MetaObject, MetaObject>();
+
+/**
+ * The read model of an `object.report`: one field per Table B row, in Table B
+ * order, plus a copy of the source the report is read from (see
+ * `reportReadSource`) when it declares one (Table A). A sourceless report yields a model with no source: it has a shape
+ * and no view, and the caller decides what that means (the runtime refuses to
+ * serve it).
+ *
+ * Cached per report node; the model is frozen. Throws what `reportShape` throws
+ * when a reference does not resolve.
+ */
+export function reportReadModel(report: MetaObject, root: MetaRoot): MetaObject {
+  const cached = READ_MODELS.get(report);
+  if (cached !== undefined) return cached;
+
+  const shape = reportShape(report, root);
+  const model = new MetaObject(report.typeId, report.name);
+  if (report.package !== undefined) model.setPackage(report.package);
+  if (report.fileDefaultPackage !== undefined) model.setFileDefaultPackage(report.fileDefaultPackage);
+  for (const f of shape.fields) model.addChild(derivedField(f));
+
+  const source = reportReadSource(report);
+  if (source !== undefined) model.addChild(copySource(source));
+
+  model.freeze();
+  READ_MODELS.set(report, model);
+  return model;
+}