@owox/backend 0.35.0 → 0.36.0

package/dist/src/common/exceptions/concurrency-limit-exceeded.exception.d.ts

@@ -1,4 +1,4 @@
 import { BusinessViolationException } from './business-violation.exception';
 export declare class ConcurrencyLimitExceededException extends BusinessViolationException {
-    constructor(message: string, errorDetails?: Record<string, unknown>);
+    constructor(message: string, errorDetails?: Record<string, unknown>, code?: string);
 }

package/dist/src/common/exceptions/concurrency-limit-exceeded.exception.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConcurrencyLimitExceededException = void 0;
 const business_violation_exception_1 = require("./business-violation.exception");
 class ConcurrencyLimitExceededException extends business_violation_exception_1.BusinessViolationException {
-    constructor(message, errorDetails) {
-        super(message, errorDetails);
+    constructor(message, errorDetails, code) {
+        super(message, errorDetails, code);
     }
 }
 exports.ConcurrencyLimitExceededException = ConcurrencyLimitExceededException;

package/dist/src/common/markdown/markdown-parser.service.d.ts

@@ -5,5 +5,7 @@ export declare enum COLOR_THEME {
 }
 export declare class MarkdownParser {
     parseToHtml(markdown: string, theme?: COLOR_THEME): Promise<string>;
+    parseToFragment(markdown: string): Promise<string>;
+    private runPipeline;
     private getColorThemeCss;
 }

package/dist/src/common/markdown/markdown-parser.service.js

@@ -84,6 +84,20 @@ var COLOR_THEME;
 })(COLOR_THEME || (exports.COLOR_THEME = COLOR_THEME = {}));
 let MarkdownParser = class MarkdownParser {
     async parseToHtml(markdown, theme = COLOR_THEME.DYNAMIC) {
+        const html = await this.runPipeline(markdown);
+        const content = `<div class="markdown-body">${html}</div>`;
+        return juice_1.default.inlineContent(content, this.getColorThemeCss(theme), {
+            preserveMediaQueries: true,
+            applyAttributesTableElements: true,
+            applyWidthAttributes: true,
+            applyHeightAttributes: true,
+            resolveCSSVariables: true,
+        });
+    }
+    async parseToFragment(markdown) {
+        return this.runPipeline(markdown);
+    }
+    async runPipeline(markdown) {
         const html = await (0, remark_1.remark)()
             .use(remark_parse_1.default)
             .use(remark_gfm_1.default)
@@ -93,14 +107,7 @@ let MarkdownParser = class MarkdownParser {
             .use(rehype_normalize_table_truncation_notice_plugin_1.rehypeNormalizeTableTruncationNoticeRows)
             .use(rehype_stringify_1.default)
             .process(markdown);
-        const content = `<div class="markdown-body">${String(html)}</div>`;
-        return juice_1.default.inlineContent(content, this.getColorThemeCss(theme), {
-            preserveMediaQueries: true,
-            applyAttributesTableElements: true,
-            applyWidthAttributes: true,
-            applyHeightAttributes: true,
-            resolveCSSVariables: true,
-        });
+        return String(html);
     }
     getColorThemeCss(theme) {
         let cssVariables;

package/dist/src/common/validators/max-byte-length.validator.d.ts

@@ -0,0 +1,2 @@
+import { ValidationOptions } from 'class-validator';
+export declare function MaxByteLength(maxSizeBytes: number, validationOptions?: ValidationOptions): (object: object, propertyName: string) => void;

package/dist/src/common/validators/max-byte-length.validator.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaxByteLength = MaxByteLength;
+const class_validator_1 = require("class-validator");
+function MaxByteLength(maxSizeBytes, validationOptions) {
+    return function (object, propertyName) {
+        (0, class_validator_1.registerDecorator)({
+            name: 'maxByteLength',
+            target: object.constructor,
+            propertyName: propertyName,
+            options: validationOptions,
+            constraints: [maxSizeBytes],
+            validator: {
+                validate(value, args) {
+                    if (typeof value !== 'string') {
+                        return true;
+                    }
+                    const [maxSize] = args.constraints;
+                    return Buffer.byteLength(value, 'utf8') <= maxSize;
+                },
+                defaultMessage(args) {
+                    const [maxSize] = args.constraints;
+                    return `${args.property} must be shorter than or equal to ${maxSize} bytes`;
+                },
+            },
+        });
+    };
+}
+//# sourceMappingURL=max-byte-length.validator.js.map

package/dist/src/config/env-validation.config.d.ts

@@ -7,6 +7,10 @@ declare const configSchema: z.ZodObject<{
     HEADERS_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
     MAX_CONNECTOR_RUNS_PER_PROJECT: z.ZodDefault<z.ZodNumber>;
     MAX_REPORT_RUNS_PER_PROJECT: z.ZodDefault<z.ZodNumber>;
+    CONNECTOR_SHORT_LINK_DOMAINS: z.ZodOptional<z.ZodString>;
+    MAX_CONNECTOR_TESTS_PER_PROJECT: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
+    MAX_CONNECTOR_TESTS_TOTAL: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
+    CONNECTOR_RUN_LOG_FLUSH_INTERVAL_MS: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
     PLUGIN_HOST_SYNC_MIN_INTERVAL_SEC: z.ZodOptional<z.ZodNumber>;
     PLUGIN_HOST_REMOTE_PROBE_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
@@ -17,6 +21,10 @@ declare const configSchema: z.ZodObject<{
     HEADERS_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
     MAX_CONNECTOR_RUNS_PER_PROJECT: z.ZodDefault<z.ZodNumber>;
     MAX_REPORT_RUNS_PER_PROJECT: z.ZodDefault<z.ZodNumber>;
+    CONNECTOR_SHORT_LINK_DOMAINS: z.ZodOptional<z.ZodString>;
+    MAX_CONNECTOR_TESTS_PER_PROJECT: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
+    MAX_CONNECTOR_TESTS_TOTAL: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
+    CONNECTOR_RUN_LOG_FLUSH_INTERVAL_MS: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
     PLUGIN_HOST_SYNC_MIN_INTERVAL_SEC: z.ZodOptional<z.ZodNumber>;
     PLUGIN_HOST_REMOTE_PROBE_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
@@ -27,6 +35,10 @@ declare const configSchema: z.ZodObject<{
     HEADERS_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
     MAX_CONNECTOR_RUNS_PER_PROJECT: z.ZodDefault<z.ZodNumber>;
     MAX_REPORT_RUNS_PER_PROJECT: z.ZodDefault<z.ZodNumber>;
+    CONNECTOR_SHORT_LINK_DOMAINS: z.ZodOptional<z.ZodString>;
+    MAX_CONNECTOR_TESTS_PER_PROJECT: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
+    MAX_CONNECTOR_TESTS_TOTAL: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
+    CONNECTOR_RUN_LOG_FLUSH_INTERVAL_MS: z.ZodEffects<z.ZodDefault<z.ZodNumber>, number, unknown>;
     PLUGIN_HOST_SYNC_MIN_INTERVAL_SEC: z.ZodOptional<z.ZodNumber>;
     PLUGIN_HOST_REMOTE_PROBE_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
 }, z.ZodTypeAny, "passthrough">>;

package/dist/src/config/env-validation.config.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateConfig = validateConfig;
 const zod_1 = require("zod");
 const constants_1 = require("./constants");
+function blankAsUnset(schema) {
+    return zod_1.z.preprocess(value => (typeof value === 'string' && value.trim() === '' ? undefined : value), schema);
+}
 const configSchema = zod_1.z
     .object({
     SCHEDULER_EXECUTION_ENABLED: zod_1.z
@@ -17,6 +20,10 @@ const configSchema = zod_1.z
     HEADERS_TIMEOUT_MS: zod_1.z.coerce.number().default(constants_1.DEFAULT_HEADERS_TIMEOUT_MS),
     MAX_CONNECTOR_RUNS_PER_PROJECT: zod_1.z.coerce.number().int().min(1).max(1000).default(3),
     MAX_REPORT_RUNS_PER_PROJECT: zod_1.z.coerce.number().int().min(1).max(1000).default(1000),
+    CONNECTOR_SHORT_LINK_DOMAINS: zod_1.z.string().trim().optional(),
+    MAX_CONNECTOR_TESTS_PER_PROJECT: blankAsUnset(zod_1.z.coerce.number().int().min(1).max(1000).default(3)),
+    MAX_CONNECTOR_TESTS_TOTAL: blankAsUnset(zod_1.z.coerce.number().int().min(1).max(1000).default(10)),
+    CONNECTOR_RUN_LOG_FLUSH_INTERVAL_MS: blankAsUnset(zod_1.z.coerce.number().int().min(0).max(3_600_000).default(2_000)),
     PLUGIN_HOST_SYNC_MIN_INTERVAL_SEC: zod_1.z.coerce.number().int().min(0).max(86_400).optional(),
     PLUGIN_HOST_REMOTE_PROBE_TIMEOUT_MS: zod_1.z.coerce
         .number()

package/dist/src/data-marts/ai-insights/agent/types.d.ts

@@ -453,6 +453,7 @@ export declare const QueryPlanSchema: z.ZodObject<{
     }>>>;
 }, "strip", z.ZodTypeAny, {
     dimensions: string[];
+    metrics: string[];
     tables: {
         fullyQualifiedName: string;
         role?: string | null | undefined;
@@ -463,7 +464,6 @@ export declare const QueryPlanSchema: z.ZodObject<{
         alias: string;
         sourceColumn: string;
     }[];
-    metrics: string[];
     metricSpecs: {
         name: string;
         required: boolean;
@@ -529,6 +529,7 @@ export declare const QueryPlanSchema: z.ZodObject<{
         required?: boolean | undefined;
     }[];
     dimensions?: string[] | undefined;
+    metrics?: string[] | undefined;
     tables?: {
         fullyQualifiedName: string;
         role?: string | null | undefined;
@@ -540,7 +541,6 @@ export declare const QueryPlanSchema: z.ZodObject<{
         sourceColumn: string;
         required?: boolean | undefined;
     }[] | undefined;
-    metrics?: string[] | undefined;
     dateField?: string | null | undefined;
     dateFilterDescription?: string | null | undefined;
     whereConditions?: string[] | undefined;
@@ -739,6 +739,7 @@ export declare const PlanModelJsonSchema: z.ZodObject<{
         }>>>;
     }, "strip", z.ZodTypeAny, {
         dimensions: string[];
+        metrics: string[];
         tables: {
             fullyQualifiedName: string;
             role?: string | null | undefined;
@@ -749,7 +750,6 @@ export declare const PlanModelJsonSchema: z.ZodObject<{
             alias: string;
             sourceColumn: string;
         }[];
-        metrics: string[];
         metricSpecs: {
             name: string;
             required: boolean;
@@ -815,6 +815,7 @@ export declare const PlanModelJsonSchema: z.ZodObject<{
             required?: boolean | undefined;
         }[];
         dimensions?: string[] | undefined;
+        metrics?: string[] | undefined;
         tables?: {
             fullyQualifiedName: string;
             role?: string | null | undefined;
@@ -826,7 +827,6 @@ export declare const PlanModelJsonSchema: z.ZodObject<{
             sourceColumn: string;
             required?: boolean | undefined;
         }[] | undefined;
-        metrics?: string[] | undefined;
         dateField?: string | null | undefined;
         dateFilterDescription?: string | null | undefined;
         whereConditions?: string[] | undefined;
@@ -855,6 +855,7 @@ export declare const PlanModelJsonSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     plan: {
         dimensions: string[];
+        metrics: string[];
         tables: {
             fullyQualifiedName: string;
             role?: string | null | undefined;
@@ -865,7 +866,6 @@ export declare const PlanModelJsonSchema: z.ZodObject<{
             alias: string;
             sourceColumn: string;
         }[];
-        metrics: string[];
         metricSpecs: {
             name: string;
             required: boolean;
@@ -935,6 +935,7 @@ export declare const PlanModelJsonSchema: z.ZodObject<{
             required?: boolean | undefined;
         }[];
         dimensions?: string[] | undefined;
+        metrics?: string[] | undefined;
         tables?: {
             fullyQualifiedName: string;
             role?: string | null | undefined;
@@ -946,7 +947,6 @@ export declare const PlanModelJsonSchema: z.ZodObject<{
             sourceColumn: string;
             required?: boolean | undefined;
         }[] | undefined;
-        metrics?: string[] | undefined;
         dateField?: string | null | undefined;
         dateFilterDescription?: string | null | undefined;
         whereConditions?: string[] | undefined;

package/dist/src/data-marts/calculated-fields/calculated-field-validator.service.js

@@ -23,6 +23,7 @@ const formula_analyzer_1 = require("./formula-analyzer");
 const formula_level_1 = require("./formula-level");
 const formula_function_dialect_1 = require("./formula-function-dialect");
 const formula_violations_1 = require("./formula-violations");
+const join_grain_1 = require("./join-grain");
 const unique_count_sources_1 = require("../dto/schemas/unique-count-sources");
 const sql_token_scanner_1 = require("./sql-token-scanner");
 const formula_reference_1 = require("./formula-reference");
@@ -63,26 +64,6 @@ function dryRunBatches(fields) {
         return [fields];
     return [aggregate, rowLevel];
 }
-function formulaDependencyGraph(fields, byName) {
-    const dependenciesOf = (field) => {
-        let references;
-        try {
-            references = (0, formula_live_reference_1.liveFormulaReferences)(field.calculated.formula);
-        }
-        catch {
-            return [];
-        }
-        const named = references
-            .filter(ref => !ref.path)
-            .map(ref => ref.field)
-            .filter(name => {
-            const found = byName.get(name);
-            return found !== undefined && (0, calculated_field_utils_1.isCalculatedField)(found);
-        });
-        return [...new Set(named)];
-    };
-    return new Map(fields.map(field => [field.name, dependenciesOf(field)]));
-}
 function formulaCycleViolations(cycles) {
     return cycles.flatMap(chain => {
         const members = [...new Set(chain)];
@@ -114,9 +95,13 @@ let CalculatedFieldValidatorService = class CalculatedFieldValidatorService {
         const byName = new Map((0, data_mart_schema_utils_1.collectFormulaReferenceableFields)(schema.fields)
             .filter(d => !(0, calculated_field_utils_1.isCalculatedField)(d.field) || topLevelCalculated.has(d.field))
             .map(d => [d.name, d.field]));
-        const joinTreeRead = await this.resolveJoinedReferences(calculated, joinTree);
+        const joinTreeRead = await this.resolveJoinedReferences(calculated, joinTree, schema.fields);
         const joinedIndex = joinTreeRead?.index;
-        const walk = (0, formula_reference_1.walkFormulaDependencies)(formulaDependencyGraph(calculated, byName));
+        const grainSources = (0, join_grain_1.buildJoinGrainSources)(joinTreeRead?.schema.availableSources ?? [], {
+            kind: 'editor',
+        });
+        const dependencies = (0, calculated_field_utils_1.formulaDependencyGraph)(calculated, byName);
+        const walk = (0, formula_reference_1.walkFormulaDependencies)(dependencies);
         const errors = formulaCycleViolations(walk.cycles);
         const warnings = [];
         const analysed = [];
@@ -151,13 +136,20 @@ let CalculatedFieldValidatorService = class CalculatedFieldValidatorService {
                 dialect,
                 knownField,
             });
+            const fieldErrors = [
+                ...joinedViolations.values(),
+                ...[...mainUniqueCountRefs].map(ref => formula_violations_1.FormulaViolations.mainUniqueCountReference(field.name, ref)),
+                ...analysis.errors,
+            ];
+            const grain = (0, join_grain_1.checkJoinGrain)({
+                fieldName: field.name,
+                aggregateCalls: analysis.aggregateCalls,
+                sources: grainSources,
+            });
+            const fieldWarnings = [...analysis.warnings, ...grain.warnings];
             analyses.set(field, {
-                errors: [
-                    ...joinedViolations.values(),
-                    ...[...mainUniqueCountRefs].map(ref => formula_violations_1.FormulaViolations.mainUniqueCountReference(field.name, ref)),
-                    ...analysis.errors,
-                ],
-                warnings: analysis.warnings,
+                errors: fieldErrors,
+                warnings: fieldWarnings,
                 level: analysis.level,
             });
             derivedLevels.set(field.name, analysis.level);
@@ -206,12 +198,12 @@ let CalculatedFieldValidatorService = class CalculatedFieldValidatorService {
         }
         return { errors, warnings };
     }
-    async resolveJoinedReferences(fields, joinTree) {
+    async resolveJoinedReferences(fields, joinTree, schemaFields) {
         if (!joinTree?.accessor.userId)
             return undefined;
         if (!fields.some(f => (0, formula_live_reference_1.hasLiveJoinedReference)(f.calculated.formula)))
             return undefined;
-        const blendable = await this.blendableSchemaService.computeBlendableSchema(joinTree.dataMartId, joinTree.projectId, joinTree.accessor);
+        const blendable = await this.blendableSchemaService.computeBlendableSchema(joinTree.dataMartId, joinTree.projectId, joinTree.accessor, { unsavedMainSchemaFields: schemaFields });
         return { schema: blendable, index: (0, calculated_field_utils_1.buildJoinedReferenceIndex)(blendable) };
     }
     resolveJoinedReference(metricName, path, refField, index, violations) {

package/dist/src/data-marts/calculated-fields/calculated-field.utils.d.ts

@@ -49,3 +49,4 @@ export declare function joinedCalculatedFieldRefusals(blendedFields: readonly {
     isCalculated?: boolean;
     sourceDataMartTitle?: string;
 }[], referencedColumns: Iterable<string>, ownColumnNames: ReadonlySet<string>): JoinedCalculatedFieldRefusal[];
+export declare function formulaDependencyGraph(fields: readonly CalculatedSchemaField[], byName: ReadonlyMap<string, DataMartSchemaField>): ReadonlyMap<string, readonly string[]>;

package/dist/src/data-marts/calculated-fields/calculated-field.utils.js

@@ -17,6 +17,7 @@ exports.brokenReferencesOf = brokenReferencesOf;
 exports.buildJoinedReferenceIndex = buildJoinedReferenceIndex;
 exports.brokenJoinedReferencesOf = brokenJoinedReferencesOf;
 exports.joinedCalculatedFieldRefusals = joinedCalculatedFieldRefusals;
+exports.formulaDependencyGraph = formulaDependencyGraph;
 const formula_live_reference_1 = require("./formula-live-reference");
 const formula_level_1 = require("./formula-level");
 const formula_function_dialect_1 = require("./formula-function-dialect");
@@ -275,4 +276,24 @@ function joinedCalculatedFieldRefusals(blendedFields, referencedColumns, ownColu
     }
     return refusals;
 }
+function formulaDependencyGraph(fields, byName) {
+    const dependenciesOf = (field) => {
+        let references;
+        try {
+            references = (0, formula_live_reference_1.liveFormulaReferences)(field.calculated.formula);
+        }
+        catch {
+            return [];
+        }
+        const named = references
+            .filter(ref => !ref.path)
+            .map(ref => ref.field)
+            .filter(name => {
+            const found = byName.get(name);
+            return found !== undefined && isCalculatedField(found);
+        });
+        return [...new Set(named)];
+    };
+    return new Map(fields.map(field => [field.name, dependenciesOf(field)]));
+}
 //# sourceMappingURL=calculated-field.utils.js.map

package/dist/src/data-marts/calculated-fields/formula-analyzer.d.ts

@@ -5,6 +5,7 @@ import { CalculatedFieldLevel } from './formula-level';
 export interface AggregateCall {
     name: string;
     owner: string;
+    distinct: boolean;
     references: FormulaReference[];
     nameStart: number;
 }

package/dist/src/data-marts/calculated-fields/formula-analyzer.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.analyzeFormula = analyzeFormula;
 const formula_reference_1 = require("./formula-reference");
+const set_quantifier_1 = require("./set-quantifier");
 const sql_token_scanner_1 = require("./sql-token-scanner");
 const sql_function_calls_1 = require("./sql-function-calls");
 const formula_violations_1 = require("./formula-violations");
@@ -90,6 +91,7 @@ function analyzeFormula(input) {
         aggregateCalls.push({
             name: call.name,
             owner: inside[0].path,
+            distinct: (0, set_quantifier_1.readSetQuantifier)(tokens, call).distinct,
             references: inside,
             nameStart: call.nameStart,
         });

package/dist/src/data-marts/calculated-fields/formula-violations.d.ts

@@ -4,6 +4,9 @@ export interface FormulaViolation {
     field: string;
     subject?: string;
 }
+export declare const UNNAMED_JOINED_SOURCE = "a joined Data Mart";
+export type MultipliedRowsOf = 'this Data Mart' | 'its parent';
+export type UniqueCountOffer = 'none' | 'report' | 'query';
 export declare const FormulaViolations: {
     levelMixing: (field: string, column: string) => FormulaViolation;
     joinedReferenceOutsideAggregate: (field: string, ref: string) => FormulaViolation;
@@ -35,6 +38,10 @@ export declare const FormulaViolations: {
     tagInStringLiteral: (field: string) => FormulaViolation;
     syntax: (field: string, detail: string) => FormulaViolation;
     unguardedDivision: (field: string, denominator?: string) => FormulaViolation;
+    joinedMeasureMultiplied: (field: string, ref: string | undefined, source: string, key: readonly string[] | undefined, multipliedBy?: string, rowsOf?: MultipliedRowsOf, uniqueCount?: UniqueCountOffer) => FormulaViolation;
+    joinedMeasureGrainUnproven: (field: string, ref: string | undefined, source: string, unprovenMart: string | undefined, collapses?: boolean, uniqueCount?: UniqueCountOffer) => FormulaViolation;
+    joinedMeasureCollapsed: (field: string, ref: string | undefined, source: string, collapsedBy?: string, uniqueCount?: UniqueCountOffer) => FormulaViolation;
+    joinedRowsExcluded: (field: string, sources: readonly string[]) => FormulaViolation;
     warehouseRejected: (field: string, detail?: string) => FormulaViolation;
     warehouseRejectedAsSet: (field: string, detail?: string) => FormulaViolation;
     otherFieldErrorsTruncated: (field: string, omitted: number) => FormulaViolation;

package/dist/src/data-marts/calculated-fields/formula-violations.js

@@ -1,6 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FormulaViolations = void 0;
+exports.FormulaViolations = exports.UNNAMED_JOINED_SOURCE = void 0;
+exports.UNNAMED_JOINED_SOURCE = 'a joined Data Mart';
+const GENERIC_MART_PHRASES = new Set(['this Data Mart', exports.UNNAMED_JOINED_SOURCE]);
+const martName = (name) => (GENERIC_MART_PHRASES.has(name) ? name : `\`${name}\``);
+const otherMartName = (name, alreadyNamed) => name === exports.UNNAMED_JOINED_SOURCE && alreadyNamed === exports.UNNAMED_JOINED_SOURCE
+    ? 'another joined Data Mart'
+    : martName(name);
+const withoutBackticks = (name) => name.split('`').join('');
+const listed = (names) => names.length < 2
+    ? (names[0] ?? '')
+    : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+const countedFrom = (ref, source) => ref === undefined
+    ? `A COUNT here reads ${martName(source)}`
+    : `\`${ref}\` comes from ${martName(source)}`;
+const joinedOn = (source, key, via) => {
+    const through = via === undefined ? undefined : `reached through ${otherMartName(via, source)}`;
+    if (key === undefined || key.length === 0) {
+        return through === undefined ? 'whose join' : `${through}, whose join`;
+    }
+    const spelled = `joined on ${key.map(k => `\`${k}\``).join(' + ')}`;
+    return `${through === undefined ? spelled : `${through} ${spelled}`}, which`;
+};
+const UNIQUE_COUNT_OFFER_CLAUSE = {
+    none: '',
+    report: ', or pick its Unique Count measure in a report',
+    query: ", or select that Data Mart's Unique Count field instead",
+};
+const distinctAdvice = (uniqueCount) => `Use COUNT(DISTINCT ...) on a column that identifies them${UNIQUE_COUNT_OFFER_CLAUSE[uniqueCount]}.`;
 exports.FormulaViolations = {
     levelMixing: (field, column) => ({
         code: 'FORMULA_LEVEL_MIXING',
@@ -212,6 +239,60 @@ exports.FormulaViolations = {
                 `NULLIF(it, 0), which turns the zero into an empty cell. Advice only: this does not block ` +
                 `the save.`,
     }),
+    joinedMeasureMultiplied: (field, ref, source, key, multipliedBy, rowsOf = 'this Data Mart', uniqueCount = 'none') => ({
+        code: 'FORMULA_JOINED_MEASURE_MULTIPLIED',
+        field,
+        ...(ref === undefined ? {} : { subject: ref }),
+        message: `${countedFrom(ref, source)}, ${joinedOn(source, key, multipliedBy)} can match several ` +
+            `rows of ${rowsOf} — so COUNT counts matches, not that Data Mart's rows. ` +
+            distinctAdvice(uniqueCount),
+    }),
+    joinedMeasureGrainUnproven: (field, ref, source, unprovenMart, collapses = false, uniqueCount = 'none') => ({
+        code: 'FORMULA_JOINED_MEASURE_GRAIN_UNPROVEN',
+        field,
+        ...(ref === undefined ? {} : { subject: ref }),
+        message: (unprovenMart === undefined
+            ? `${countedFrom(ref, source)}, and it can't be checked whether the join matches one row ` +
+                `or several — if several, COUNT is inflated.`
+            : `${countedFrom(ref, source)}, and ${otherMartName(unprovenMart, source)} has no ` +
+                `Primary Key, so it can't be checked whether the join matches one row or several — if ` +
+                `several, COUNT is inflated. Set a Primary Key to find out.`) +
+            (collapses
+                ? ` Several rows of ${martName(source)} can also share one join key value, so COUNT can ` +
+                    `come out lower too. ${distinctAdvice(uniqueCount)}`
+                : ''),
+    }),
+    joinedMeasureCollapsed: (field, ref, source, collapsedBy, uniqueCount = 'none') => ({
+        code: 'FORMULA_JOINED_MEASURE_COLLAPSED',
+        field,
+        ...(ref === undefined ? {} : { subject: ref }),
+        message: `${countedFrom(ref, source)}, ` +
+            (collapsedBy === undefined ? '' : `reached through ${otherMartName(collapsedBy, source)}, `) +
+            `where several rows can share one join key value — so COUNT counts the rows of this Data ` +
+            `Mart they match, which can be fewer than that Data Mart's own rows. ` +
+            distinctAdvice(uniqueCount),
+    }),
+    joinedRowsExcluded: (field, sources) => {
+        const named = [
+            ...new Set(sources.filter(s => s !== exports.UNNAMED_JOINED_SOURCE).map(withoutBackticks)),
+        ];
+        const unnamed = sources.filter(s => s === exports.UNNAMED_JOINED_SOURCE).length;
+        const anonymous = unnamed === 1
+            ? named.length === 0
+                ? exports.UNNAMED_JOINED_SOURCE
+                : 'another joined Data Mart'
+            : `${unnamed} ${named.length === 0 ? '' : 'other '}joined Data Marts`;
+        const names = unnamed === 0 ? named : [...named, anonymous];
+        return {
+            code: 'FORMULA_JOINED_ROWS_EXCLUDED',
+            field,
+            message: named.length + unnamed === 1
+                ? `This formula reads ${listed(names)} through a join. Its rows that match nothing ` +
+                    `here are dropped, so the result may not match that Data Mart's own totals.`
+                : `This formula reads ${listed(names)} through joins. Their rows that match nothing ` +
+                    `here are dropped, so the result may not match those Data Marts' own totals.`,
+        };
+    },
     warehouseRejected: (field, detail) => ({
         code: 'FORMULA_WAREHOUSE_REJECTED',
         field,

package/dist/src/data-marts/calculated-fields/join-grain.d.ts

@@ -0,0 +1,32 @@
+import type { AvailableSourceDto, BlendedFieldDto, MainGrainCollapse, MainGrainMultiplication } from '../dto/domain/blendable-schema.dto';
+import { AggregateCall } from './formula-analyzer';
+import { FormulaViolation } from './formula-violations';
+export interface JoinGrainSource {
+    multiplication: MainGrainMultiplication;
+    keyFields: readonly string[];
+    collapse: MainGrainCollapse;
+    title: string;
+    titleHidden: boolean;
+    uniqueCountAvailable: boolean;
+    reader: JoinGrainAudience['kind'];
+    fieldNames?: ReadonlyMap<string, string>;
+    unprovenAt?: string;
+    multipliedAt?: string;
+    collapsedAt?: string;
+}
+export type JoinGrainAudience = {
+    kind: 'editor';
+} | {
+    kind: 'agent';
+    blendedFields: readonly BlendedFieldDto[];
+};
+export declare function buildJoinGrainSources(sources: readonly AvailableSourceDto[], audience: JoinGrainAudience): Map<string, JoinGrainSource>;
+export interface JoinGrainInput {
+    fieldName: string;
+    aggregateCalls: readonly AggregateCall[];
+    sources: ReadonlyMap<string, JoinGrainSource>;
+}
+export declare function checkJoinGrain(input: JoinGrainInput): {
+    warnings: FormulaViolation[];
+};
+export declare function withoutUntouchedJoinAdvisories(warnings: readonly FormulaViolation[], touchedFields: ReadonlySet<string>, primaryKeyChanged: boolean): FormulaViolation[];