0pt/tests/analytics/analytics-domain-model.test.ts

/**
 * BI-P002 (domain model) + BI-P003 (data tiers), the parts provable without
 * infrastructure. The Postgres half — real tables, real immutability
 * triggers, real tenant scoping — is
 * tests/analytics/analytics-domain-postgres.realinfra.test.ts.
 *
 * The registry-vs-migration test below is the one that earns its place: it
 * reads sql/008_analytics_domain_model.sql from disk and asserts a CREATE
 * TABLE exists for every one of the nineteen canonical entities. A future
 * rename, or an entity quietly dropped from the migration, fails HERE rather
 * than at 3am against a database that turns out to be missing a table.
 */
import { describe, it, expect } from 'vitest';
import fs from 'node:fs';
import path from 'node:path';
import {
  ANALYTICS_DOMAIN_ENTITIES,
  ANALYTICS_ENTITY_TABLES,
  IMMUTABLE_VERSION_ENTITIES,
} from '@/src/analytics/domain/entities';
import {
  ANALYTICS_TIERS,
  assertReadableByBiSurface,
  assertTierLineageSane,
  BI_READABLE_TIERS,
  isAnalyticsTier,
  TIER_RANK,
} from '@/src/analytics/domain/tiers';

const MIGRATION = fs.readFileSync(path.join(process.cwd(), 'sql', '008_analytics_domain_model.sql'), 'utf8');

describe('BI-P002 canonical entity set', () => {
  it('lists exactly the nineteen entities the program names, verbatim', () => {
    expect(ANALYTICS_DOMAIN_ENTITIES).toEqual([
      'AnalyticsDataset',
      'DatasetVersion',
      'DatasetField',
      'DatasetGrant',
      'MetricDefinition',
      'MetricVersion',
      'DimensionDefinition',
      'SemanticModel',
      'AnalyticsQuery',
      'QueryExecution',
      'QueryResult',
      'DashboardDefinition',
      'DashboardVersion',
      'ReportDefinition',
      'ReportRun',
      'DataQualityRule',
      'DataQualityRun',
      'LineageReference',
      'BIApplicationBinding',
    ]);
    expect(ANALYTICS_DOMAIN_ENTITIES).toHaveLength(19);
  });

  it('sql/008 defines a table for every entity (no entity is a type without storage)', () => {
    const missing: string[] = [];
    for (const entity of ANALYTICS_DOMAIN_ENTITIES) {
      const table = ANALYTICS_ENTITY_TABLES[entity];
      if (!new RegExp(`CREATE TABLE IF NOT EXISTS ${table}\\b`).test(MIGRATION)) {
        missing.push(`${entity} -> ${table}`);
      }
    }
    expect(missing).toEqual([]);
  });

  it('every tenant-owned table carries tenant_id AND project_id', () => {
    // Split on the table definitions and check each block.
    const blocks = MIGRATION.split(/CREATE TABLE IF NOT EXISTS /).slice(1);
    const offenders: string[] = [];
    for (const block of blocks) {
      const name = block.split(/[\s(]/)[0];
      if (!Object.values(ANALYTICS_ENTITY_TABLES).includes(name)) continue;
      const body = block.slice(0, block.indexOf(');'));
      if (!/\btenant_id TEXT NOT NULL\b/.test(body) || !/\bproject_id TEXT NOT NULL\b/.test(body)) {
        offenders.push(name);
      }
    }
    expect(offenders).toEqual([]);
  });

  it('the four immutable version entities have a BEFORE UPDATE OR DELETE trigger in sql/008', () => {
    expect(IMMUTABLE_VERSION_ENTITIES).toEqual([
      'DatasetVersion',
      'MetricVersion',
      'SemanticModel',
      'DashboardVersion',
    ]);
    for (const entity of IMMUTABLE_VERSION_ENTITIES) {
      const table = ANALYTICS_ENTITY_TABLES[entity];
      expect(
        new RegExp(`BEFORE UPDATE OR DELETE ON ${table}\\b`).test(MIGRATION),
        `${entity} (${table}) has no immutability trigger`,
      ).toBe(true);
    }
  });

  it('BIApplicationBinding storage carries NO credential column — the ownership boundary is structural', () => {
    const block = MIGRATION.split('CREATE TABLE IF NOT EXISTS opt_analytics_bi_application_binding')[1] ?? '';
    const body = block.slice(0, block.indexOf(');'));
    for (const forbidden of ['password', 'dsn', 'secret', 'connection_string', 'clickhouse_url', 'token']) {
      expect(body.toLowerCase()).not.toContain(forbidden);
    }
  });

  it('sql/008 is idempotent-shaped: every CREATE is IF NOT EXISTS / OR REPLACE', () => {
    const creates =
      MIGRATION.match(/^CREATE (TABLE|INDEX|TRIGGER|FUNCTION|OR REPLACE FUNCTION)[^\n]*/gm) ?? [];
    const nonIdempotent = creates.filter(
      (line) => !/IF NOT EXISTS/.test(line) && !/OR REPLACE/.test(line) && !/^CREATE TRIGGER/.test(line),
    );
    expect(nonIdempotent).toEqual([]);
    // Triggers cannot take IF NOT EXISTS in Postgres, so each one must be
    // preceded by a DROP TRIGGER IF EXISTS to stay replayable.
    const triggers = MIGRATION.match(/^CREATE TRIGGER (\w+)/gm) ?? [];
    for (const t of triggers) {
      const name = t.replace('CREATE TRIGGER ', '');
      expect(MIGRATION).toContain(`DROP TRIGGER IF EXISTS ${name}`);
    }
  });
});

describe('BI-P003 analytics data tiers', () => {
  it('canonicalizes exactly RAW / NORMALIZED / CURATED / SERVING', () => {
    expect(ANALYTICS_TIERS).toEqual(['RAW', 'NORMALIZED', 'CURATED', 'SERVING']);
    expect(isAnalyticsTier('CURATED')).toBe(true);
    expect(isAnalyticsTier('raw')).toBe(false);
    expect(isAnalyticsTier('BRONZE')).toBe(false);
  });

  it('no business dashboard reads a RAW/NORMALIZED dataset by default', () => {
    expect(BI_READABLE_TIERS).toEqual(['SERVING', 'CURATED']);
    for (const tier of ['RAW', 'NORMALIZED'] as const) {
      expect(() =>
        assertReadableByBiSurface({ dataset_id: 'ds_1', tier }, 'dashboard:exec-overview'),
      ).toThrowError(/may not read/);
    }
    for (const tier of ['SERVING', 'CURATED'] as const) {
      expect(() => assertReadableByBiSurface({ dataset_id: 'ds_1', tier }, 'dashboard:x')).not.toThrow();
    }
  });

  it('a recorded exception is the only way a RAW dataset reaches a BI surface', () => {
    expect(() =>
      assertReadableByBiSurface(
        {
          dataset_id: 'ds_1',
          tier: 'RAW',
          raw_access_exception: 'INC-2026-09-06 forensic review, expires 2026-10-01',
        },
        'dashboard:incident',
      ),
    ).not.toThrow();
    // An empty/whitespace "exception" is not an exception.
    expect(() =>
      assertReadableByBiSurface(
        { dataset_id: 'ds_1', tier: 'RAW', raw_access_exception: '  ' },
        'dashboard:x',
      ),
    ).toThrowError(/may not read/);
  });

  it('tier order is enforced: a CURATED dataset cannot be built from SERVING', () => {
    expect(TIER_RANK.RAW).toBeLessThan(TIER_RANK.NORMALIZED);
    expect(TIER_RANK.NORMALIZED).toBeLessThan(TIER_RANK.CURATED);
    expect(TIER_RANK.CURATED).toBeLessThan(TIER_RANK.SERVING);
    expect(() => assertTierLineageSane('CURATED', 'SERVING')).toThrowError(/tier order/);
    expect(() => assertTierLineageSane('SERVING', 'CURATED')).not.toThrow();
    expect(() => assertTierLineageSane('CURATED', 'CURATED')).not.toThrow();
  });

  it('sql/008 constrains tier at the DATABASE level, not only in TypeScript', () => {
    expect(MIGRATION).toContain("CHECK (tier IN ('RAW','NORMALIZED','CURATED','SERVING'))");
  });

  it("BI-P003's eight required declarations are all NOT NULL in sql/008", () => {
    const block = MIGRATION.split('CREATE TABLE IF NOT EXISTS opt_analytics_dataset ')[1] ?? '';
    const body = block.slice(0, block.indexOf(');'));
    for (const col of [
      'tier',
      'schema_contract_id',
      'owner_id',
      'source_ref',
      'freshness_slo_seconds',
      'retention_days',
      'classification',
      'quality_rule_ids',
    ]) {
      expect(new RegExp(`\\b${col}\\b[^,]*NOT NULL`).test(body), `${col} is nullable`).toBe(true);
    }
  });
});