dzql 0.5.33 → 0.6.0

package/src/cli/compiler/ir.ts

@@ -0,0 +1,233 @@
+import type {
+  DomainConfig,
+  EntityConfig,
+  SubscribableConfig,
+  IncludeConfig,
+  GraphRuleActionConfig,
+  GraphRuleConfig,
+  ManyToManyConfig,
+  DomainIR,
+  EntityIR,
+  SubscribableIR,
+  IncludeIR,
+  CustomFunctionIR,
+  ManyToManyIR,
+  GraphRuleIR
+} from "../../shared/ir.js";
+
+/**
+ * Parses a graph rule config into IR format.
+ * Handles both formats:
+ * 1. Direct: { actions: [...] }
+ * 2. Named: { rule_name: { description, condition, actions } }
+ */
+function parseGraphRules(rules: Record<string, GraphRuleConfig> | { actions: GraphRuleActionConfig[] } | undefined): GraphRuleIR[] {
+  if (!rules) return [];
+
+  const allActions: GraphRuleIR[] = [];
+
+  // Helper to extract target from action config
+  const getTarget = (action: GraphRuleActionConfig): string => {
+    // For validate/execute, use 'function'; for delete/update use 'target'; for create use 'entity'; for reactor use 'name'
+    return action.function || action.target || action.entity || action.name || '';
+  };
+
+  // Helper to build a GraphRuleIR from an action config
+  const buildRuleIR = (
+    action: GraphRuleActionConfig,
+    ruleName?: string,
+    ruleDescription?: string,
+    ruleCondition?: string
+  ): GraphRuleIR => {
+    return {
+      trigger: 'create', // Will be set by caller
+      action: action.type as 'create' | 'update' | 'delete' | 'reactor' | 'validate' | 'execute',
+      target: getTarget(action),
+      ruleName,
+      description: ruleDescription,
+      condition: ruleCondition,
+      params: action.params || action.data || {},
+      match: action.match,
+      error_message: action.error_message
+    };
+  };
+
+  // Case 1: Direct rule (has 'actions' at top level)
+  if ('actions' in rules && Array.isArray(rules.actions)) {
+    for (const action of rules.actions) {
+      allActions.push(buildRuleIR(action));
+    }
+    return allActions;
+  }
+
+  // Case 2: Named rules (iterate values)
+  for (const [ruleName, ruleConfig] of Object.entries(rules)) {
+    if (ruleConfig && typeof ruleConfig === 'object' && 'actions' in ruleConfig && Array.isArray(ruleConfig.actions)) {
+      for (const action of ruleConfig.actions) {
+        allActions.push(buildRuleIR(
+          action,
+          ruleName,
+          ruleConfig.description,
+          ruleConfig.condition
+        ));
+      }
+    }
+  }
+
+  return allActions;
+}
+
+/**
+ * Parses include config (handles both string shorthand and full object)
+ */
+function parseIncludes(rawIncludes: Record<string, string | IncludeConfig> | undefined): Record<string, IncludeIR> {
+  const parsed: Record<string, IncludeIR> = {};
+  if (!rawIncludes) return parsed;
+
+  for (const [key, val] of Object.entries(rawIncludes)) {
+    // Handle shorthand string: "org": "organisations"
+    if (typeof val === 'string') {
+      parsed[key] = {
+        relation: key,
+        entity: val,
+        includes: {}
+      };
+    } else {
+      // Handle full object: "sites": { entity: "sites", ... }
+      parsed[key] = {
+        relation: key,
+        entity: val.entity || key,
+        filter: val.filter,
+        includes: parseIncludes(val.includes as Record<string, string | IncludeConfig> | undefined)
+      };
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Generates IR from a typed domain configuration
+ */
+export function generateIR(domain: DomainConfig): DomainIR {
+  const entities: Record<string, EntityIR> = {};
+
+  // --- ENTITIES ---
+  for (const [name, config] of Object.entries(domain.entities)) {
+    const columns: Array<{ name: string; type: string; isArray: boolean }> = [];
+    const pk: string[] = [];
+
+    // Parse Schema
+    for (const [colName, colType] of Object.entries(config.schema)) {
+      columns.push({
+        name: colName,
+        type: colType,
+        isArray: colType.includes('[]')
+      });
+
+      if (colType.toUpperCase().includes('PRIMARY KEY')) {
+        pk.push(colName);
+      }
+    }
+
+    // Check for explicit primaryKey array in config (for composite PKs)
+    if (config.primaryKey && Array.isArray(config.primaryKey) && config.primaryKey.length > 0) {
+      pk.length = 0; // Clear any auto-detected PKs
+      pk.push(...config.primaryKey);
+    }
+
+    // Default PK if none found
+    if (pk.length === 0 && columns.some(c => c.name === 'id')) {
+      pk.push('id');
+    }
+
+    // Parse permissions
+    const rawPerms = config.permissions || {};
+    const permissions = {
+      view: rawPerms.view || [],
+      create: rawPerms.create || [],
+      update: rawPerms.update || [],
+      delete: rawPerms.delete || []
+    };
+
+    // Parse Graph Rules
+    const rawRules = config.graphRules || {};
+
+    const onCreateRules = parseGraphRules(rawRules.on_create);
+    onCreateRules.forEach(r => r.trigger = 'create');
+
+    const onUpdateRules = parseGraphRules(rawRules.on_update);
+    onUpdateRules.forEach(r => r.trigger = 'update');
+
+    const onDeleteRules = parseGraphRules(rawRules.on_delete);
+    onDeleteRules.forEach(r => r.trigger = 'delete');
+
+    // Parse M2M relationships
+    const rawM2M = config.manyToMany || {};
+    const manyToMany: Record<string, ManyToManyIR> = {};
+    for (const [relationKey, m2mConfig] of Object.entries(rawM2M)) {
+      manyToMany[relationKey] = {
+        junctionTable: m2mConfig.junctionTable,
+        localKey: m2mConfig.localKey,
+        foreignKey: m2mConfig.foreignKey,
+        targetEntity: m2mConfig.targetEntity,
+        idField: m2mConfig.idField,
+        expand: m2mConfig.expand || false
+      };
+    }
+
+    entities[name] = {
+      name,
+      table: name,
+      primaryKey: pk,
+      columns,
+      labelField: config.label || 'id',
+      softDelete: config.softDelete || false,
+      managed: config.managed !== false, // Default to true, only false if explicitly set
+      hidden: config.hidden || [],
+      fieldDefaults: config.fieldDefaults || {},
+      permissions,
+      relationships: {},
+      manyToMany,
+      graphRules: {
+        onCreate: onCreateRules,
+        onUpdate: onUpdateRules,
+        onDelete: onDeleteRules
+      }
+    };
+  }
+
+  // --- SUBSCRIBABLES ---
+  const subscribables: Record<string, SubscribableIR> = {};
+
+  if (domain.subscribables) {
+    for (const [name, config] of Object.entries(domain.subscribables)) {
+      subscribables[name] = {
+        name,
+        params: config.params || {},
+        root: config.root || { entity: '', key: '' },
+        includes: parseIncludes(config.includes as Record<string, string | IncludeConfig> | undefined),
+        scopeTables: config.scopeTables || [],
+        canSubscribe: config.canSubscribe || []
+      };
+    }
+  }
+
+  // --- CUSTOM FUNCTIONS ---
+  const customFunctions: CustomFunctionIR[] = [];
+
+  if (domain.customFunctions) {
+    for (const fn of domain.customFunctions) {
+      customFunctions.push({
+        name: fn.name,
+        sql: fn.sql,
+        args: fn.args || ['p_user_id', 'p_params']
+      });
+    }
+  }
+
+  return {
+    entities,
+    subscribables,
+    customFunctions
+  };
+}

package/src/cli/compiler/loader.ts

@@ -0,0 +1,132 @@
+import { resolve } from "path";
+import type { DomainConfig, EntityConfig, SubscribableConfig, CustomFunctionConfig } from "../../shared/ir.js";
+
+/**
+ * Validates that an entity config has the required fields
+ */
+function validateEntityConfig(name: string, config: unknown): EntityConfig {
+  if (!config || typeof config !== 'object') {
+    throw new Error(`Entity '${name}' must be an object`);
+  }
+
+  const c = config as Record<string, unknown>;
+
+  if (!c.schema || typeof c.schema !== 'object') {
+    throw new Error(`Entity '${name}' must have a 'schema' object`);
+  }
+
+  // Return typed config (schema is the only required field)
+  return config as EntityConfig;
+}
+
+/**
+ * Validates that a subscribable config has the required fields
+ */
+function validateSubscribableConfig(name: string, config: unknown): SubscribableConfig {
+  if (!config || typeof config !== 'object') {
+    throw new Error(`Subscribable '${name}' must be an object`);
+  }
+
+  const c = config as Record<string, unknown>;
+
+  if (!c.root || typeof c.root !== 'object') {
+    throw new Error(`Subscribable '${name}' must have a 'root' object`);
+  }
+
+  const root = c.root as Record<string, unknown>;
+  if (!root.entity || typeof root.entity !== 'string') {
+    throw new Error(`Subscribable '${name}' root must have an 'entity' string`);
+  }
+
+  return config as SubscribableConfig;
+}
+
+/**
+ * Validates a custom function config
+ */
+function validateCustomFunctionConfig(fn: unknown, index: number): CustomFunctionConfig {
+  if (!fn || typeof fn !== 'object') {
+    throw new Error(`Custom function at index ${index} must be an object`);
+  }
+
+  const f = fn as Record<string, unknown>;
+
+  if (!f.name || typeof f.name !== 'string') {
+    throw new Error(`Custom function at index ${index} must have a 'name' string`);
+  }
+
+  if (!f.sql || typeof f.sql !== 'string') {
+    throw new Error(`Custom function '${f.name}' must have a 'sql' string`);
+  }
+
+  return fn as CustomFunctionConfig;
+}
+
+/**
+ * Loads and validates a domain configuration file
+ */
+export async function loadDomain(filePath: string): Promise<DomainConfig> {
+  // Simple resolve against CWD
+  const absolutePath = resolve(process.cwd(), filePath);
+  console.log(`[Compiler] Resolving path: ${filePath}`);
+  console.log(`[Compiler] Absolute path: ${absolutePath}`);
+
+  try {
+    // Bun can import .ts files directly
+    const module = await import(absolutePath);
+
+    if (!module.entities) {
+      throw new Error(`Module ${filePath} must export 'entities' object.`);
+    }
+
+    if (typeof module.entities !== 'object') {
+      throw new Error(`Module ${filePath} 'entities' must be an object.`);
+    }
+
+    // Validate entities
+    const entities: Record<string, EntityConfig> = {};
+    for (const [name, config] of Object.entries(module.entities)) {
+      entities[name] = validateEntityConfig(name, config);
+    }
+
+    console.log(`[Compiler] Loaded ${Object.keys(entities).length} entities.`);
+
+    // Validate subscribables if present
+    const subscribables: Record<string, SubscribableConfig> = {};
+    if (module.subscribables) {
+      if (typeof module.subscribables !== 'object') {
+        throw new Error(`Module ${filePath} 'subscribables' must be an object.`);
+      }
+
+      for (const [name, config] of Object.entries(module.subscribables)) {
+        subscribables[name] = validateSubscribableConfig(name, config);
+      }
+
+      console.log(`[Compiler] Loaded ${Object.keys(subscribables).length} subscribables.`);
+    }
+
+    // Validate custom functions if present
+    const customFunctions: CustomFunctionConfig[] = [];
+    if (module.customFunctions) {
+      if (!Array.isArray(module.customFunctions)) {
+        throw new Error(`Module ${filePath} 'customFunctions' must be an array.`);
+      }
+
+      for (let i = 0; i < module.customFunctions.length; i++) {
+        customFunctions.push(validateCustomFunctionConfig(module.customFunctions[i], i));
+      }
+
+      console.log(`[Compiler] Loaded ${customFunctions.length} custom functions.`);
+    }
+
+    return {
+      entities,
+      subscribables,
+      customFunctions
+    };
+
+  } catch (error) {
+    console.error(`[Compiler] Failed to load domain module:`, error);
+    throw error;
+  }
+}

package/src/cli/compiler/permissions.ts

@@ -0,0 +1,227 @@
+/**
+ * Compiles a permission rule into SQL.
+ *
+ * Supported formats:
+ * - Simple field check: @author_id (implies author_id == user_id)
+ * - Explicit comparison: @field == @user_id
+ * - Single-hop traversal: @org_id->acts_for[org_id=$]{active}.user_id
+ * - Multi-hop traversal: @venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id
+ * - Deep traversal: @site_id->sites.venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id
+ *
+ * @param entityName - The entity name
+ * @param rule - The permission rule string
+ * @param context - Optional context (unused)
+ * @param dataVar - Either a JSONB variable name (e.g., 'p_data') or a table name (e.g., 'packages')
+ *                  When it's a table name, we use table.column syntax instead of jsonb->>'column'
+ */
+export function compilePermission(entityName: string, rule: string, context: any, dataVar: string = 'p_data'): string {
+  // Determine if dataVar is a JSONB variable or a table name
+  // JSONB variables typically start with p_ or v_ (e.g., p_data, v_old_data)
+  const isJsonb = dataVar.startsWith('p_') || dataVar.startsWith('v_');
+
+  // Helper to access a field value
+  const fieldAccess = (field: string) => {
+    if (isJsonb) {
+      return `(${dataVar}->>'${field}')::int`;
+    } else {
+      return `${dataVar}.${field}`;
+    }
+  };
+
+  // Case 1: Simple Field Check (@author_id)
+  // Implies: author_id == user_id
+  if (rule.match(/^@[a-zA-Z0-9_]+$/)) {
+    const field = rule.substring(1);
+    return `${fieldAccess(field)} = p_user_id`;
+  }
+
+  // Case 1b: Explicit Comparison (@field == @user_id)
+  const comparisonMatch = rule.match(/^@([a-zA-Z0-9_]+)\s*==\s*@user_id$/);
+  if (comparisonMatch) {
+      const field = comparisonMatch[1];
+      return `${fieldAccess(field)} = p_user_id`;
+  }
+
+  // Case 2: Graph Traversal (supports unlimited depth)
+  // Format: @local_field->table.field->table[filter=$]{condition}.user_id
+  if (rule.includes('->')) {
+    return compileTraversalPath(rule, dataVar, isJsonb);
+  }
+
+  // Case 3: Table-first lookup (e.g., contractor_rights[package_id=@package_id]{active}.field->...)
+  // This pattern starts with a table reference and filter, not a field reference
+  const tableFirstMatch = rule.match(/^([a-zA-Z0-9_]+)\[([^\]]+)\]/);
+  if (tableFirstMatch) {
+    // This is a complex pattern that needs special handling
+    // For now, return FALSE and log a warning
+    console.warn(`[Compiler] Warning: Table-first permission path '${rule}' not fully supported yet.`);
+    return 'FALSE';
+  }
+
+  return 'FALSE'; // Default deny
+}
+
+/**
+ * Compiles a multi-hop traversal path into SQL with nested subqueries.
+ *
+ * Example: @venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id
+ *
+ * Algorithm:
+ * 1. Split on '->' to get hops
+ * 2. First hop is the source field from the record
+ * 3. Intermediate hops traverse through tables via FK lookups
+ * 4. Final hop is an EXISTS check with conditions
+ */
+function compileTraversalPath(rule: string, dataVar: string, isJsonb: boolean): string {
+  const hops = rule.split('->');
+
+  if (hops.length < 2) {
+    return 'FALSE';
+  }
+
+  const firstHop = hops[0];
+
+  // Check if this is a table-first pattern (doesn't start with @)
+  // e.g., contractor_rights[package_id=@package_id]{active}.contractor_org_id
+  if (!firstHop.startsWith('@')) {
+    // This is a complex pattern: table[filter].field -> ...
+    // Parse the first hop to get the table, filter, and field
+    const tableFirstMatch = firstHop.match(/^([a-zA-Z0-9_]+)\[([^\]]+)\](\{[^}]+\})?\.([a-zA-Z0-9_]+)$/);
+    if (tableFirstMatch) {
+      const [_, lookupTable, filterExpr, condExpr, outputField] = tableFirstMatch;
+
+      // Parse the filter: package_id=@package_id
+      const filterMatch = filterExpr.match(/([a-zA-Z0-9_]+)=@([a-zA-Z0-9_]+)/);
+      if (!filterMatch) {
+        console.warn(`[Compiler] Warning: Cannot parse filter '${filterExpr}' in permission path.`);
+        return 'FALSE';
+      }
+      const [__, filterField, sourceRefField] = filterMatch;
+
+      // Get the source field value
+      const sourceValue = isJsonb
+        ? `(${dataVar}->>'${sourceRefField}')::int`
+        : `${dataVar}.${sourceRefField}`;
+
+      // Parse condition like {active}
+      let conditionClause = '';
+      if (condExpr) {
+        const cond = condExpr.replace(/[{}]/g, '');
+        if (cond.match(/^[a-zA-Z0-9_]+$/)) {
+          conditionClause = ` AND ${lookupTable}.${cond} = true`;
+        } else {
+          conditionClause = ` AND ${lookupTable}.${cond}`;
+        }
+      }
+
+      // Build subquery to get the output field from the lookup table
+      let valueExpr = `(SELECT ${outputField} FROM ${lookupTable} WHERE ${lookupTable}.${filterField} = ${sourceValue}${conditionClause})`;
+
+      // Now process remaining hops (all but the last, which is the EXISTS check)
+      for (let i = 1; i < hops.length - 1; i++) {
+        const hop = hops[i];
+        const dotMatch = hop.match(/^([a-zA-Z0-9_]+)\.([a-zA-Z0-9_]+)$/);
+        if (dotMatch) {
+          const table = dotMatch[1];
+          const field = dotMatch[2];
+          valueExpr = `(SELECT ${field} FROM ${table} WHERE id = ${valueExpr})`;
+        }
+      }
+
+      // Final hop: EXISTS check
+      return buildFinalExistsCheck(hops[hops.length - 1], valueExpr);
+    }
+
+    // Unrecognized pattern
+    console.warn(`[Compiler] Warning: Unrecognized table-first pattern '${firstHop}'. Returning FALSE.`);
+    return 'FALSE';
+  }
+
+  // First hop: source field from record (e.g., @venue_id -> venue_id)
+  const sourceField = firstHop.replace(/^@/, '');
+
+  // Start building the value expression
+  let valueExpr = isJsonb
+    ? `(${dataVar}->>'${sourceField}')::int`
+    : `${dataVar}.${sourceField}`;
+
+  // Process intermediate hops (all but the last)
+  for (let i = 1; i < hops.length - 1; i++) {
+    const hop = hops[i];
+
+    // Parse table.field format (e.g., venues.org_id)
+    const dotMatch = hop.match(/^([a-zA-Z0-9_]+)\.([a-zA-Z0-9_]+)$/);
+    if (dotMatch) {
+      const table = dotMatch[1];
+      const field = dotMatch[2];
+      // Wrap in subquery: (SELECT field FROM table WHERE id = previousValue)
+      valueExpr = `(SELECT ${field} FROM ${table} WHERE id = ${valueExpr})`;
+    } else {
+      // Just a table name - assume we're looking up by id and continuing with id
+      const table = hop.replace(/\[.*\]/, '').replace(/\{.*\}/, '').replace(/\..*$/, '');
+      valueExpr = `(SELECT id FROM ${table} WHERE id = ${valueExpr})`;
+    }
+  }
+
+  // Final hop: EXISTS check with the target table
+  return buildFinalExistsCheck(hops[hops.length - 1], valueExpr);
+}
+
+/**
+ * Builds the final EXISTS check for a permission path.
+ *
+ * @param finalHop - The final hop string (e.g., "acts_for[org_id=$]{active}.user_id")
+ * @param valueExpr - The SQL expression for the value to join on
+ */
+function buildFinalExistsCheck(finalHop: string, valueExpr: string): string {
+  // Parse final hop components
+  // Format: table[filter=$]{condition}.user_id
+  const tableMatch = finalHop.match(/^([a-zA-Z0-9_]+)/);
+  if (!tableMatch) return 'FALSE';
+  const targetTable = tableMatch[1];
+
+  // Extract filter: [org_id=$]
+  const filterMatch = finalHop.match(/\[([a-zA-Z0-9_]+)=\$\]/);
+  const joinField = filterMatch ? filterMatch[1] : null;
+
+  // Extract condition: {active} or {role='admin'}
+  const condMatch = finalHop.match(/\{([^}]+)\}/);
+  const condition = condMatch ? condMatch[1] : null;
+
+  // Extract target field: .user_id
+  const targetFieldMatch = finalHop.match(/\.([a-zA-Z0-9_]+)$/);
+  const targetField = targetFieldMatch ? targetFieldMatch[1] : null;
+
+  // Build EXISTS query
+  const conditions: string[] = [];
+
+  // Join condition
+  if (joinField) {
+    conditions.push(`${targetTable}.${joinField} = ${valueExpr}`);
+  } else {
+    // Implicit join by id
+    conditions.push(`${targetTable}.id = ${valueExpr}`);
+  }
+
+  // Temporal/active condition
+  if (condition) {
+    // Handle simple boolean condition like {active}
+    if (condition.match(/^[a-zA-Z0-9_]+$/)) {
+      conditions.push(`${targetTable}.${condition} = true`);
+    } else {
+      // Handle complex condition like {role='admin'}
+      conditions.push(`${targetTable}.${condition}`);
+    }
+  }
+
+  // User check (final target field)
+  if (targetField === 'user_id') {
+    conditions.push(`${targetTable}.user_id = p_user_id`);
+  } else if (targetField) {
+    conditions.push(`${targetTable}.${targetField} = p_user_id`);
+  }
+
+  const whereClause = conditions.join(' AND ');
+
+  return `EXISTS (SELECT 1 FROM ${targetTable} WHERE ${whereClause})`;
+}