@rangka/core 0.0.1

package/src/plugins/loader.ts

@@ -0,0 +1,126 @@
+import type {
+  PluginDefinition,
+  PluginBootContext,
+  DataAdapter,
+  PluginLifecycleEvent,
+  LifecycleHandler,
+} from './types.js';
+import { AdapterRegistry } from './adapter-registry.js';
+import { PluginLifecycleManager } from './lifecycle.js';
+
+export class DuplicatePluginError extends Error {
+  constructor(public readonly pluginName: string) {
+    super(`Plugin "${pluginName}" is already registered`);
+    this.name = 'DuplicatePluginError';
+  }
+}
+
+export class PluginConfigError extends Error {
+  constructor(
+    public readonly pluginName: string,
+    public readonly field: string,
+  ) {
+    super(`Plugin "${pluginName}" requires config field "${field}"`);
+    this.name = 'PluginConfigError';
+  }
+}
+
+export class MissingAdapterImplementationError extends Error {
+  constructor(
+    public readonly pluginName: string,
+    public readonly adapterName: string,
+  ) {
+    super(
+      `Plugin "${pluginName}" declares adapter "${adapterName}" in provides but did not implement it during boot`,
+    );
+    this.name = 'MissingAdapterImplementationError';
+  }
+}
+
+export interface LoadPluginsOptions {
+  plugins: PluginDefinition[];
+  config?: Record<string, Record<string, unknown>>;
+}
+
+export interface LoadPluginsResult {
+  adapterRegistry: AdapterRegistry;
+  lifecycleManager: PluginLifecycleManager;
+}
+
+export async function loadPlugins(options: LoadPluginsOptions): Promise<LoadPluginsResult> {
+  const { plugins, config = {} } = options;
+  const adapterRegistry = new AdapterRegistry();
+  const lifecycleManager = new PluginLifecycleManager();
+
+  const seen = new Set<string>();
+  for (const plugin of plugins) {
+    if (seen.has(plugin.name)) {
+      throw new DuplicatePluginError(plugin.name);
+    }
+    seen.add(plugin.name);
+  }
+
+  for (const plugin of plugins) {
+    const pluginConfig = resolveConfig(plugin, config[plugin.name] ?? {});
+    const implemented = new Set<string>();
+
+    const adapterProxies: Record<string, { implement(impl: DataAdapter): void }> = {};
+    if (plugin.provides?.adapters) {
+      for (const decl of plugin.provides.adapters) {
+        adapterProxies[decl.name] = {
+          implement(impl: DataAdapter) {
+            adapterRegistry.register(decl.name, impl);
+            implemented.add(decl.name);
+          },
+        };
+      }
+    }
+
+    const ctx: PluginBootContext = {
+      config: pluginConfig,
+      adapters: adapterProxies,
+      on(event: PluginLifecycleEvent, handler: LifecycleHandler) {
+        lifecycleManager.register(event, handler);
+      },
+    };
+
+    await plugin.boot(ctx);
+
+    if (plugin.provides?.adapters) {
+      for (const decl of plugin.provides.adapters) {
+        if (!implemented.has(decl.name)) {
+          throw new MissingAdapterImplementationError(plugin.name, decl.name);
+        }
+      }
+    }
+  }
+
+  return { adapterRegistry, lifecycleManager };
+}
+
+function resolveConfig(
+  plugin: PluginDefinition,
+  userConfig: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (!plugin.config) return userConfig;
+
+  for (const [key, schema] of Object.entries(plugin.config)) {
+    if (userConfig[key] !== undefined) {
+      result[key] = userConfig[key];
+    } else if (schema.default !== undefined) {
+      result[key] = schema.default;
+    } else if (schema.required) {
+      throw new PluginConfigError(plugin.name, key);
+    }
+  }
+
+  for (const [key, value] of Object.entries(userConfig)) {
+    if (!(key in result)) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}

package/src/plugins/types.ts

@@ -0,0 +1,76 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export type AdapterCapability =
+  | 'read'
+  | 'list'
+  | 'filter'
+  | 'sort'
+  | 'create'
+  | 'update'
+  | 'delete';
+
+export interface FilterExpression {
+  field: string;
+  operator: string;
+  value: unknown;
+}
+
+export interface ListQuery {
+  page?: number;
+  pageSize?: number;
+  sort?: { field: string; direction: 'asc' | 'desc' };
+  filters?: FilterExpression[];
+}
+
+export interface ListResult {
+  data: Record<string, unknown>[];
+  total?: number;
+  hasMore?: boolean;
+}
+
+export interface DataAdapter {
+  get(model: string, id: string): Promise<Record<string, unknown> | null>;
+  list?(model: string, query: ListQuery): Promise<ListResult>;
+  create?(model: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+  update?(
+    model: string,
+    id: string,
+    data: Record<string, unknown>,
+  ): Promise<Record<string, unknown>>;
+  delete?(model: string, id: string): Promise<void>;
+  filter?(model: string, filters: FilterExpression[]): Promise<ListResult>;
+  batchGet?(model: string, ids: string[]): Promise<Record<string, unknown>[]>;
+}
+
+export type PluginLifecycleEvent =
+  | 'beforeBoot'
+  | 'afterBoot'
+  | 'beforeRequest'
+  | 'afterRequest'
+  | 'beforeShutdown';
+
+export interface PluginConfigField {
+  type: string;
+  required?: boolean;
+  default?: unknown;
+}
+
+export interface PluginProvides {
+  adapters?: Array<{ name: string; capabilities: AdapterCapability[] }>;
+}
+
+export interface PluginBootContext {
+  config: Record<string, unknown>;
+  adapters: Record<string, { implement(impl: DataAdapter): void }>;
+  on(event: PluginLifecycleEvent, handler: (...args: any[]) => Promise<void>): void;
+}
+
+export interface PluginDefinition {
+  name: string;
+  version: string;
+  config?: Record<string, PluginConfigField>;
+  provides?: PluginProvides;
+  boot(ctx: PluginBootContext): void | Promise<void>;
+}
+
+export type LifecycleHandler = (...args: any[]) => Promise<void>;

package/src/plugins/validator.ts

@@ -0,0 +1,141 @@
+import type { AdapterRegistry } from './adapter-registry.js';
+import type { AdapterCapability, PluginDefinition } from './types.js';
+import type { ResolvedModel } from '../schema/types.js';
+
+export interface PluginValidationError {
+  type:
+    | 'MISSING_ADAPTER_IMPL'
+    | 'UNRESOLVED_SOURCE'
+    | 'CONFIG_REQUIRED'
+    | 'DUPLICATE_PLUGIN'
+    | 'CAPABILITY_VIOLATION';
+  plugin?: string;
+  model?: string;
+  message: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: PluginValidationError[];
+  warnings: string[];
+}
+
+export function validatePluginSetup(
+  adapterRegistry: AdapterRegistry,
+  externalModels: ResolvedModel[],
+  pluginDefinitions: PluginDefinition[],
+  adapterCapabilities?: Record<string, AdapterCapability[]>,
+): ValidationResult {
+  const errors: PluginValidationError[] = [];
+  const warnings: string[] = [];
+
+  checkDuplicatePlugins(pluginDefinitions, errors);
+  checkAdapterImplementations(pluginDefinitions, adapterRegistry, errors);
+  checkExternalModelSources(externalModels, adapterRegistry, errors);
+  checkCapabilityViolations(externalModels, adapterCapabilities ?? {}, errors);
+  checkBatchGetSupport(externalModels, adapterRegistry, warnings);
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+function checkDuplicatePlugins(plugins: PluginDefinition[], errors: PluginValidationError[]): void {
+  const seen = new Set<string>();
+  for (const plugin of plugins) {
+    if (seen.has(plugin.name)) {
+      errors.push({
+        type: 'DUPLICATE_PLUGIN',
+        plugin: plugin.name,
+        message: `Duplicate plugin name: "${plugin.name}"`,
+      });
+    }
+    seen.add(plugin.name);
+  }
+}
+
+function checkAdapterImplementations(
+  plugins: PluginDefinition[],
+  adapterRegistry: AdapterRegistry,
+  errors: PluginValidationError[],
+): void {
+  for (const plugin of plugins) {
+    if (!plugin.provides?.adapters) continue;
+    for (const decl of plugin.provides.adapters) {
+      if (!adapterRegistry.has(decl.name)) {
+        errors.push({
+          type: 'MISSING_ADAPTER_IMPL',
+          plugin: plugin.name,
+          message: `Plugin "${plugin.name}" declares adapter "${decl.name}" but it is not registered`,
+        });
+      }
+    }
+  }
+}
+
+function checkExternalModelSources(
+  models: ResolvedModel[],
+  adapterRegistry: AdapterRegistry,
+  errors: PluginValidationError[],
+): void {
+  for (const model of models) {
+    if (!model.source) continue;
+    if (!adapterRegistry.has(model.source)) {
+      errors.push({
+        type: 'UNRESOLVED_SOURCE',
+        model: model.qualifiedName,
+        message: `External model "${model.qualifiedName}" references adapter "${model.source}" which is not registered`,
+      });
+    }
+  }
+}
+
+function checkBatchGetSupport(
+  models: ResolvedModel[],
+  adapterRegistry: AdapterRegistry,
+  warnings: string[],
+): void {
+  for (const model of models) {
+    if (!model.source) continue;
+    if (!adapterRegistry.has(model.source)) continue;
+
+    const adapter = adapterRegistry.get(model.source);
+    if (!adapter.batchGet) {
+      warnings.push(
+        `Adapter "${model.source}" used by "${model.qualifiedName}" does not implement batchGet. Relationship resolution will use N+1 get calls.`,
+      );
+    }
+  }
+}
+
+function checkCapabilityViolations(
+  models: ResolvedModel[],
+  adapterCapabilities: Record<string, AdapterCapability[]>,
+  errors: PluginValidationError[],
+): void {
+  for (const model of models) {
+    if (!model.source) continue;
+    const declared = adapterCapabilities[model.source];
+    if (!declared) continue;
+
+    const capabilities = new Set(declared);
+
+    if (!capabilities.has('read')) {
+      errors.push({
+        type: 'CAPABILITY_VIOLATION',
+        model: model.qualifiedName,
+        message: `External model "${model.qualifiedName}" uses adapter "${model.source}" which does not declare the required "read" capability`,
+      });
+    }
+
+    if (!capabilities.has('list')) {
+      errors.push({
+        type: 'CAPABILITY_VIOLATION',
+        model: model.qualifiedName,
+        message: `External model "${model.qualifiedName}" uses adapter "${model.source}" which does not declare "list" capability. List endpoints will not be generated.`,
+      });
+    }
+  }
+}

package/src/schema/__tests__/registry-models-by-module.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { SchemaRegistry } from '../registry.js';
+import type { ResolvedModel } from '../types.js';
+
+function makeModel(module: string, name: string): ResolvedModel {
+  return {
+    qualifiedName: `${module}.${name}`,
+    app: 'test',
+    module,
+    name,
+    auditLog: false,
+    traits: [],
+    fields: [{ name: 'id', config: { type: 'string' }, provenance: { source: 'base' } }],
+    indexes: [],
+  };
+}
+
+describe('SchemaRegistry.getModelsByModule', () => {
+  it('returns empty map for empty registry', () => {
+    const registry = new SchemaRegistry([]);
+    const result = registry.getModelsByModule();
+    expect(result.size).toBe(0);
+  });
+
+  it('groups models by module', () => {
+    const models = [
+      makeModel('sales', 'invoice'),
+      makeModel('sales', 'customer'),
+      makeModel('accounting', 'journal_entry'),
+    ];
+    const registry = new SchemaRegistry(models);
+    const result = registry.getModelsByModule();
+
+    expect(result.size).toBe(2);
+    expect(result.get('sales')).toHaveLength(2);
+    expect(result.get('accounting')).toHaveLength(1);
+  });
+
+  it('preserves model data', () => {
+    const models = [makeModel('sales', 'invoice')];
+    const registry = new SchemaRegistry(models);
+    const result = registry.getModelsByModule();
+    const salesModels = result.get('sales')!;
+    expect(salesModels[0].qualifiedName).toBe('sales.invoice');
+    expect(salesModels[0].name).toBe('invoice');
+  });
+
+  it('handles single module with multiple models', () => {
+    const models = [
+      makeModel('hr', 'employee'),
+      makeModel('hr', 'department'),
+      makeModel('hr', 'leave_request'),
+    ];
+    const registry = new SchemaRegistry(models);
+    const result = registry.getModelsByModule();
+    expect(result.get('hr')).toHaveLength(3);
+  });
+});

package/src/schema/registry.ts

@@ -0,0 +1,93 @@
+import type { ResolvedModel, ResolvedField, ModelRelationship, ExtensionSource } from './types.js';
+import { buildRelationships } from './relationships.js';
+
+/**
+ * Central registry providing lookup access to all resolved models,
+ * their relationships, and extension metadata.
+ */
+export class SchemaRegistry {
+  private readonly modelMap: Map<string, ResolvedModel>;
+  private readonly relationships: ModelRelationship[];
+  private readonly extensionSourceMap: Map<string, ExtensionSource[]>;
+
+  constructor(models: ResolvedModel[]) {
+    this.modelMap = new Map();
+    for (const model of models) {
+      this.modelMap.set(model.qualifiedName, model);
+    }
+    this.relationships = buildRelationships(models);
+    this.extensionSourceMap = this.buildExtensionSourceMap(models);
+  }
+
+  /** Retrieve a single model by its fully qualified name (e.g. "sales.Invoice"). */
+  getModel(qualifiedName: string): ResolvedModel | undefined {
+    return this.modelMap.get(qualifiedName);
+  }
+
+  /** Return all registered models. */
+  getAllModels(): ResolvedModel[] {
+    return Array.from(this.modelMap.values());
+  }
+
+  /** Return the field definitions for a given model. */
+  getFieldsForModel(qualifiedName: string): ResolvedField[] {
+    const model = this.modelMap.get(qualifiedName);
+    if (!model) return [];
+    return model.fields;
+  }
+
+  /** Return all computed relationships across the schema. */
+  getRelationships(): ModelRelationship[] {
+    return this.relationships;
+  }
+
+  /** Return relationships originating from a specific model. */
+  getRelationshipsForModel(qualifiedName: string): ModelRelationship[] {
+    return this.relationships.filter((r) => r.from === qualifiedName);
+  }
+
+  /** Return extension source metadata for a model (which apps contributed fields). */
+  getExtensionSources(qualifiedName: string): ExtensionSource[] {
+    return this.extensionSourceMap.get(qualifiedName) ?? [];
+  }
+
+  /** Group all models by their module name. */
+  getModelsByModule(): Map<string, ResolvedModel[]> {
+    const moduleToModels = new Map<string, ResolvedModel[]>();
+    for (const model of this.modelMap.values()) {
+      const group = moduleToModels.get(model.module) ?? [];
+      group.push(model);
+      moduleToModels.set(model.module, group);
+    }
+    return moduleToModels;
+  }
+
+  /**
+   * Builds a map from model name to the list of apps that extended it with extra fields.
+   */
+  private buildExtensionSourceMap(models: ResolvedModel[]): Map<string, ExtensionSource[]> {
+    const map = new Map<string, ExtensionSource[]>();
+
+    for (const model of models) {
+      const extensionFields = model.fields.filter((f) => f.provenance.source === 'extension');
+      if (extensionFields.length === 0) continue;
+
+      // Group extension fields by the app that contributed them
+      const fieldsByApp = new Map<string, string[]>();
+      for (const field of extensionFields) {
+        const contributingApp = field.provenance.app!;
+        const fieldNames = fieldsByApp.get(contributingApp) ?? [];
+        fieldNames.push(field.name);
+        fieldsByApp.set(contributingApp, fieldNames);
+      }
+
+      const sources: ExtensionSource[] = [];
+      for (const [app, fields] of fieldsByApp) {
+        sources.push({ app, fields });
+      }
+      map.set(model.qualifiedName, sources);
+    }
+
+    return map;
+  }
+}

package/src/schema/relationships.ts

@@ -0,0 +1,93 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { ResolvedModel, ModelRelationship } from './types.js';
+
+/**
+ * Scans all models for relational fields and produces a flat list of relationships.
+ */
+export function buildRelationships(models: ResolvedModel[]): ModelRelationship[] {
+  const relationships: ModelRelationship[] = [];
+
+  for (const model of models) {
+    for (const field of model.fields) {
+      const relationship = fieldToRelationship(field.config, field.name, model, models);
+      if (relationship) {
+        relationships.push(relationship);
+      }
+    }
+  }
+
+  return relationships;
+}
+
+/**
+ * Converts a single field config into a ModelRelationship, or returns null
+ * if the field is not a relational type.
+ */
+function fieldToRelationship(
+  config: any,
+  fieldName: string,
+  sourceModel: ResolvedModel,
+  allModels: ResolvedModel[],
+): ModelRelationship | null {
+  const from = sourceModel.qualifiedName;
+
+  switch (config.type) {
+    case 'link': {
+      const targetModel = resolveModelName(config.model, sourceModel.module, allModels);
+      return { type: 'link', from, field: fieldName, to: targetModel };
+    }
+    case 'hasMany': {
+      const targetModel = resolveModelName(config.model, sourceModel.module, allModels);
+      return {
+        type: 'hasMany',
+        from,
+        field: fieldName,
+        to: targetModel,
+        foreignKey: config.foreignKey,
+      };
+    }
+    case 'children': {
+      const targetModel = resolveModelName(config.model, sourceModel.module, allModels);
+      return {
+        type: 'children',
+        from,
+        field: fieldName,
+        to: targetModel,
+        foreignKey: config.foreignKey,
+      };
+    }
+    case 'manyToMany': {
+      const targetModel = resolveModelName(config.model, sourceModel.module, allModels);
+      const throughModel = resolveModelName(config.through, sourceModel.module, allModels);
+      return { type: 'manyToMany', from, field: fieldName, to: targetModel, through: throughModel };
+    }
+    case 'dynamicLink': {
+      return {
+        type: 'dynamicLink',
+        from,
+        field: fieldName,
+        to: '*',
+        modelField: config.modelField,
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Resolves an unqualified model name (e.g. "Invoice") to its fully qualified form
+ * (e.g. "accounting.Invoice") by checking the current app first, then all models.
+ */
+function resolveModelName(name: string, currentModule: string, models: ResolvedModel[]): string {
+  if (name.includes('.')) return name;
+
+  const qualifiedInCurrentModule = `${currentModule}.${name}`;
+  const foundInCurrentModule = models.find((m) => m.qualifiedName === qualifiedInCurrentModule);
+  if (foundInCurrentModule) return qualifiedInCurrentModule;
+
+  const foundElsewhere = models.find((m) => m.name === name);
+  if (foundElsewhere) return foundElsewhere.qualifiedName;
+
+  return qualifiedInCurrentModule;
+}

package/src/schema/types.ts

@@ -0,0 +1,43 @@
+import type { FieldConfig, ModelConfig, ScopeConfig } from '@rangka/shared';
+
+export interface FieldProvenance {
+  source: 'base' | 'trait' | 'extension';
+  app?: string;
+  trait?: string;
+}
+
+export interface ResolvedField {
+  name: string;
+  config: FieldConfig;
+  provenance: FieldProvenance;
+}
+
+export interface ResolvedModel {
+  qualifiedName: string;
+  app: string;
+  module: string;
+  name: string;
+  label?: string;
+  naming?: ModelConfig['naming'];
+  scope?: ScopeConfig;
+  auditLog: boolean;
+  traits: string[];
+  fields: ResolvedField[];
+  indexes: ModelConfig['indexes'];
+  source?: string;
+}
+
+export interface ModelRelationship {
+  type: 'link' | 'hasMany' | 'children' | 'manyToMany' | 'dynamicLink';
+  from: string;
+  field: string;
+  to: string;
+  foreignKey?: string;
+  through?: string;
+  modelField?: string;
+}
+
+export interface ExtensionSource {
+  app: string;
+  fields: string[];
+}

package/src/services/__tests__/integration.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { ServiceRegistry } from '../registry.js';
+import { HookRegistry } from '../../hooks/registry.js';
+import { executeHookPipeline } from '../../hooks/executor.js';
+import { SchemaRegistry } from '../../schema/registry.js';
+import { EventBus } from '../../events/bus.js';
+
+describe('hook → service → db integration', () => {
+  it('hook calls ctx.service() which accesses ctx.db', async () => {
+    const serviceRegistry = new ServiceRegistry();
+    const dbCalls: string[] = [];
+
+    serviceRegistry.register({
+      name: 'pricing',
+      factory: (_ctx) => ({
+        getDiscount: async (customerId: unknown) => {
+          dbCalls.push(`query:${customerId}`);
+          return 0.1;
+        },
+      }),
+    });
+
+    const hookRegistry = new HookRegistry();
+    hookRegistry.register(
+      'sales.order',
+      {
+        beforeSave: async (doc: any, ctx: any) => {
+          const pricing = ctx.service('pricing') as any;
+          const discount = await pricing.getDiscount(doc.customer_id);
+          doc.discount = discount;
+        },
+      },
+      'sales',
+    );
+
+    const schema = new SchemaRegistry([]);
+    const eventBus = new EventBus();
+    const auth = { user: { id: '1' }, roles: ['Admin'], scopes: {} } as any;
+
+    const mockTrx = {
+      transaction: () => ({
+        execute: async (fn: any) => fn(mockTrx),
+      }),
+    } as any;
+
+    const chain = hookRegistry.getChain('sales.order')!;
+    const result = await executeHookPipeline({
+      model: 'sales.order',
+      operation: 'create',
+      chain,
+      doc: { customer_id: 'cust-1', total: 100 } as any,
+      db: mockTrx,
+      schema,
+      auth,
+      eventBus,
+      serviceRegistry,
+      execute: async (doc) => doc,
+    });
+
+    expect(result.discount).toBe(0.1);
+    expect(dbCalls).toEqual(['query:cust-1']);
+  });
+});