@rangka/core 0.0.1

package/src/boot/project-scanner.ts

@@ -0,0 +1,397 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type {
+  ModuleConfig,
+  ModelConfig,
+  HooksConfig,
+  ExtensionConfig,
+  JobConfig,
+  PageDefinition,
+  RolesConfig,
+  RangkaConfig,
+} from '@rangka/shared';
+import type { DiscoveredApp, RangkaPackageInfo } from './types.js';
+import type { ServiceDefinition } from '../services/types.js';
+import type { FixtureDefinition } from '../fixtures/types.js';
+import { validatePageSources, detectDuplicatePageKeys } from './page-utils.js';
+
+// ---------- Public types ----------
+
+export interface ProjectScanResult {
+  app: DiscoveredApp;
+  rangkaConfig: RangkaConfig;
+}
+
+export interface DatabaseConfig {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+}
+
+// ---------- Scanner ----------
+
+export class ProjectScanner {
+  constructor(private readonly root: string) {}
+
+  /**
+   * Scans the project root and returns a fully-assembled DiscoveredApp
+   * along with the rangka.config.ts settings.
+   */
+  async scan(): Promise<ProjectScanResult> {
+    const rangkaConfig = await this.loadRangkaConfig();
+    const modules = await this.scanModules();
+
+    // Collect artifacts from every module
+    const schemas: DiscoveredApp['schemas'] = [];
+    const hooks: NonNullable<DiscoveredApp['hooks']> = [];
+    const roles: NonNullable<DiscoveredApp['roles']> = [];
+    const services: ServiceDefinition[] = [];
+    const jobs: Array<{ name: string; config: JobConfig }> = [];
+    const fixtures: FixtureDefinition[] = [];
+    const pages: Array<{ module: string; page: PageDefinition }> = [];
+
+    for (const moduleConfig of modules) {
+      await this.collectModuleArtifacts(moduleConfig, {
+        schemas,
+        hooks,
+        roles,
+        services,
+        jobs,
+        fixtures,
+        pages,
+      });
+    }
+
+    const extensions = await this.scanExtensions();
+
+    this.warnAboutPageIssues(pages, schemas);
+
+    const app = this.buildDiscoveredApp(modules, {
+      schemas,
+      extensions,
+      modules,
+      hooks,
+      roles,
+      jobs,
+      services,
+      fixtures,
+      pages,
+    });
+
+    return { app, rangkaConfig };
+  }
+
+  // ---------- Top-level loading ----------
+
+  /** Loads rangka.config.ts from the project root. */
+  private async loadRangkaConfig(): Promise<RangkaConfig> {
+    const configPath = path.join(this.root, 'rangka.config.ts');
+    await this.assertFileExists(configPath, 'No rangka.config.ts found');
+    const mod = await this.importFile(configPath);
+    return mod.default;
+  }
+
+  /** Discovers all sub-modules under the modules/ directory. */
+  private async scanModules(): Promise<ModuleConfig[]> {
+    const modulesDir = path.join(this.root, 'modules');
+    if (!(await this.dirExists(modulesDir))) return [];
+
+    const entries = await fs.readdir(modulesDir, { withFileTypes: true });
+    const modules: ModuleConfig[] = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const moduleFile = path.join(modulesDir, entry.name, 'module.ts');
+      if (!(await this.fileExists(moduleFile))) continue;
+
+      const mod = await this.importFile(moduleFile);
+      modules.push(mod.default);
+    }
+
+    return modules;
+  }
+
+  // ---------- Per-module artifact collection ----------
+
+  /**
+   * Scans a single module's subdirectories and pushes discovered
+   * artifacts into the corresponding accumulator arrays.
+   */
+  private async collectModuleArtifacts(
+    moduleConfig: ModuleConfig,
+    accumulators: {
+      schemas: DiscoveredApp['schemas'];
+      hooks: NonNullable<DiscoveredApp['hooks']>;
+      roles: NonNullable<DiscoveredApp['roles']>;
+      services: ServiceDefinition[];
+      jobs: Array<{ name: string; config: JobConfig }>;
+      fixtures: FixtureDefinition[];
+      pages: Array<{ module: string; page: PageDefinition }>;
+    },
+  ): Promise<void> {
+    const moduleName = moduleConfig.name;
+
+    // Models — flat .ts files in models/
+    const models = await this.scanModels(moduleName);
+    for (const schema of models) {
+      accumulators.schemas.push({ module: moduleName, schema });
+    }
+
+    // Hooks — separate hooks/ directory
+    accumulators.hooks.push(...(await this.scanHooksDirectory(moduleName)));
+
+    // Roles — per-module roles.ts file
+    const roles = await this.scanRoles(moduleName);
+    if (roles) {
+      accumulators.roles.push({ config: roles, app: moduleName });
+    }
+
+    // Services, jobs, fixtures, pages
+    accumulators.services.push(...(await this.scanServices(moduleName)));
+    accumulators.jobs.push(...(await this.scanJobs(moduleName)));
+    accumulators.fixtures.push(...(await this.scanFixtures(moduleName)));
+    accumulators.pages.push(...(await this.scanPages(moduleName)));
+  }
+
+  // ---------- Model scanning (flat files) ----------
+
+  /** Scans .ts files in modules/<name>/models/ for model definitions. */
+  private async scanModels(moduleName: string): Promise<ModelConfig[]> {
+    const modelsDir = path.join(this.root, 'modules', moduleName, 'models');
+    return this.scanTsFilesWithDefault<ModelConfig>(modelsDir);
+  }
+
+  // ---------- Hooks scanning (separate directory) ----------
+
+  /**
+   * Scans .ts files in modules/<name>/hooks/ for hook definitions.
+   * Each file exports defineHooks(model, config) which returns { model, ...config }.
+   */
+  private async scanHooksDirectory(
+    moduleName: string,
+  ): Promise<Array<{ model: string; hooks: HooksConfig }>> {
+    const hooksDir = path.join(this.root, 'modules', moduleName, 'hooks');
+    if (!(await this.dirExists(hooksDir))) return [];
+
+    const entries = await fs.readdir(hooksDir, { withFileTypes: true });
+    const result: Array<{ model: string; hooks: HooksConfig }> = [];
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;
+      try {
+        const mod = await this.importFile(path.join(hooksDir, entry.name));
+        if (mod.default) {
+          const { model, ...hooksConfig } = mod.default;
+          const qualifiedModel = model.includes('.') ? model : `${moduleName}.${model}`;
+          result.push({ model: qualifiedModel, hooks: hooksConfig });
+        }
+      } catch (err) {
+        console.warn(
+          `[rangka] Failed to import hook file modules/${moduleName}/hooks/${entry.name}: ${(err as Error).message}`,
+        );
+      }
+    }
+
+    return result;
+  }
+
+  // ---------- Roles scanning (per-module file) ----------
+
+  /** Loads modules/<name>/roles.ts if it exists. Returns the RolesConfig or null. */
+  private async scanRoles(moduleName: string): Promise<RolesConfig | null> {
+    const rolesFile = path.join(this.root, 'modules', moduleName, 'roles.ts');
+    if (!(await this.fileExists(rolesFile))) return null;
+
+    const mod = await this.importFile(rolesFile);
+    return mod.default ?? null;
+  }
+
+  // ---------- Other artifact scanners ----------
+
+  /** Scans .ts files in modules/<name>/services/ for service definitions. */
+  private async scanServices(moduleName: string): Promise<ServiceDefinition[]> {
+    const servicesDir = path.join(this.root, 'modules', moduleName, 'services');
+    return this.scanTsFilesWithDefault<ServiceDefinition>(servicesDir);
+  }
+
+  /** Scans .ts files in modules/<name>/jobs/ for job definitions. */
+  private async scanJobs(moduleName: string): Promise<Array<{ name: string; config: JobConfig }>> {
+    const jobsDir = path.join(this.root, 'modules', moduleName, 'jobs');
+    const rawJobs = await this.scanTsFilesWithDefault<{ name: string } & JobConfig>(jobsDir);
+    return rawJobs.map(({ name, ...config }) => ({ name, config }));
+  }
+
+  /** Scans .ts files in modules/<name>/fixtures/ for fixture definitions. */
+  private async scanFixtures(moduleName: string): Promise<FixtureDefinition[]> {
+    const fixturesDir = path.join(this.root, 'modules', moduleName, 'fixtures');
+    return this.scanTsFilesWithDefault<FixtureDefinition>(fixturesDir);
+  }
+
+  /** Scans .ts files in modules/<name>/pages/ for page definitions (with error handling). */
+  private async scanPages(
+    moduleName: string,
+  ): Promise<Array<{ module: string; page: PageDefinition }>> {
+    const pagesDir = path.join(this.root, 'modules', moduleName, 'pages');
+    if (!(await this.dirExists(pagesDir))) return [];
+
+    const entries = await fs.readdir(pagesDir, { withFileTypes: true });
+    const pages: Array<{ module: string; page: PageDefinition }> = [];
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;
+      try {
+        const mod = await this.importFile(path.join(pagesDir, entry.name));
+        if (mod.default) {
+          pages.push({ module: moduleName, page: mod.default });
+        }
+      } catch (err) {
+        console.warn(
+          `[rangka] Failed to import page file modules/${moduleName}/pages/${entry.name}: ${(err as Error).message}`,
+        );
+      }
+    }
+
+    return pages;
+  }
+
+  /** Scans extensions/ directory for extension definitions. */
+  private async scanExtensions(): Promise<DiscoveredApp['extensions']> {
+    const extensionsDir = path.join(this.root, 'extensions');
+    if (!(await this.dirExists(extensionsDir))) return [];
+
+    const entries = await fs.readdir(extensionsDir, { withFileTypes: true });
+    const extensions: DiscoveredApp['extensions'] = [];
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;
+      const mod = await this.importFile(path.join(extensionsDir, entry.name));
+      if (mod.default) {
+        const { target, ...config } = mod.default;
+        extensions.push({ target, config: config as ExtensionConfig });
+      }
+    }
+
+    return extensions;
+  }
+
+  // ---------- Validation ----------
+
+  /** Emits console warnings for invalid page sources or duplicate page keys. */
+  private warnAboutPageIssues(
+    pages: Array<{ module: string; page: PageDefinition }>,
+    schemas: DiscoveredApp['schemas'],
+  ): void {
+    if (pages.length === 0) return;
+
+    const knownModels = new Set(schemas.map((s) => `${s.module}.${s.schema.name}`));
+    const sourceWarnings = validatePageSources(pages, knownModels);
+    const duplicateWarnings = detectDuplicatePageKeys(pages);
+
+    for (const warning of [...sourceWarnings, ...duplicateWarnings]) {
+      console.warn(`[rangka] ${warning.pageKey} (${warning.location}): ${warning.message}`);
+    }
+  }
+
+  // ---------- Assembly ----------
+
+  /** Builds the final DiscoveredApp object, omitting empty optional arrays. */
+  private buildDiscoveredApp(
+    modules: ModuleConfig[],
+    parts: {
+      schemas: DiscoveredApp['schemas'];
+      extensions: DiscoveredApp['extensions'];
+      modules: ModuleConfig[];
+      hooks: NonNullable<DiscoveredApp['hooks']>;
+      roles: NonNullable<DiscoveredApp['roles']>;
+      jobs: Array<{ name: string; config: JobConfig }>;
+      services: ServiceDefinition[];
+      fixtures: FixtureDefinition[];
+      pages: Array<{ module: string; page: PageDefinition }>;
+    },
+  ): DiscoveredApp {
+    const appName = modules[0]?.name ?? 'app';
+
+    const packageInfo: RangkaPackageInfo = {
+      packageName: appName,
+      path: this.root,
+      rangka: { type: 'app', entrypoint: './rangka.config.ts' },
+    };
+
+    const config: ModuleConfig = {
+      name: appName,
+      label: appName,
+    };
+
+    return {
+      packageInfo,
+      config,
+      schemas: parts.schemas,
+      extensions: parts.extensions,
+      modules: parts.modules.length > 0 ? parts.modules : undefined,
+      hooks: parts.hooks.length > 0 ? parts.hooks : undefined,
+      roles: parts.roles.length > 0 ? parts.roles : undefined,
+      jobs: parts.jobs.length > 0 ? parts.jobs : undefined,
+      services: parts.services.length > 0 ? parts.services : undefined,
+      fixtures: parts.fixtures.length > 0 ? parts.fixtures : undefined,
+      pages: parts.pages.length > 0 ? parts.pages : undefined,
+    };
+  }
+
+  // ---------- Filesystem utilities ----------
+
+  /** Dynamically imports a TypeScript file by path. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private async importFile(filePath: string): Promise<any> {
+    return import(`file://${filePath}?t=${Date.now()}`);
+  }
+
+  /** Returns true if the path exists and is a regular file. */
+  private async fileExists(filePath: string): Promise<boolean> {
+    try {
+      const stat = await fs.stat(filePath);
+      return stat.isFile();
+    } catch {
+      return false;
+    }
+  }
+
+  /** Returns true if the path exists and is a directory. */
+  private async dirExists(dirPath: string): Promise<boolean> {
+    try {
+      const stat = await fs.stat(dirPath);
+      return stat.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /** Throws if the file does not exist. */
+  private async assertFileExists(filePath: string, message: string): Promise<void> {
+    if (!(await this.fileExists(filePath))) {
+      throw new Error(`${message}: ${filePath}`);
+    }
+  }
+
+  /**
+   * Generic helper: reads all .ts files in a directory and collects
+   * their default exports into an array. Skips files without a default export.
+   * Returns an empty array if the directory doesn't exist.
+   */
+  private async scanTsFilesWithDefault<T>(dirPath: string): Promise<T[]> {
+    if (!(await this.dirExists(dirPath))) return [];
+
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const results: T[] = [];
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;
+      const mod = await this.importFile(path.join(dirPath, entry.name));
+      if (mod.default) results.push(mod.default);
+    }
+
+    return results;
+  }
+}

package/src/boot/schema-loader.ts

@@ -0,0 +1,26 @@
+import type { ModelConfig, ExtensionConfig } from '@rangka/shared';
+import type { DiscoveredApp } from './types.js';
+
+export interface SchemaLoadResult {
+  schemas: Array<{ app: string; module: string; schema: ModelConfig }>;
+  extensions: Array<{ app: string; target: string; config: ExtensionConfig }>;
+}
+
+export function loadSchemas(apps: DiscoveredApp[]): SchemaLoadResult {
+  const schemas: SchemaLoadResult['schemas'] = [];
+  const extensions: SchemaLoadResult['extensions'] = [];
+
+  for (const app of apps) {
+    const appName = app.config.name;
+
+    for (const { module, schema } of app.schemas) {
+      schemas.push({ app: appName, module, schema });
+    }
+
+    for (const { target, config } of app.extensions ?? []) {
+      extensions.push({ app: appName, target, config });
+    }
+  }
+
+  return { schemas, extensions };
+}

package/src/boot/schema-merger.ts

@@ -0,0 +1,125 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { ResolvedField, ResolvedModel } from '../schema/types.js';
+import type { SchemaLoadResult } from './schema-loader.js';
+import { getTraitFields } from './traits.js';
+import { SchemaConflictError } from './types.js';
+
+export interface MergeResult {
+  models: ResolvedModel[];
+}
+
+/**
+ * Merge loaded schemas and extensions into a flat list of resolved models.
+ * Traits inject fields first, then base fields, then extensions add theirs.
+ * Throws SchemaConflictError if an extension tries to redefine an existing field.
+ */
+export function mergeSchemas(loadResult: SchemaLoadResult): MergeResult {
+  const modelMap = new Map<string, ResolvedModel>();
+
+  // Phase 1: Build base models from schemas (trait fields + declared fields)
+  for (const { app, module, schema } of loadResult.schemas) {
+    const qualifiedName = `${module}.${schema.name}`;
+    const fields = buildBaseFields(app, schema);
+
+    modelMap.set(qualifiedName, {
+      qualifiedName,
+      app,
+      module,
+      name: schema.name,
+      label: schema.label,
+      naming: schema.naming,
+      scope: schema.scope,
+      auditLog: schema.auditLog !== false,
+      traits: schema.traits ?? [],
+      fields,
+      indexes: schema.indexes,
+    });
+  }
+
+  // Phase 2: Apply extensions (add fields from other apps/modules)
+  for (const { app, target, config } of loadResult.extensions) {
+    const model = modelMap.get(target);
+    if (!model) continue;
+
+    if (config.fields) {
+      applyExtensionFields(model, config.fields, app, target);
+    }
+  }
+
+  return {
+    models: Array.from(modelMap.values()),
+  };
+}
+
+// --- Helpers ---
+
+/** Build the initial field list for a model: trait-injected fields followed by declared fields. */
+function buildBaseFields(
+  app: string,
+  schema: { name: string; traits?: string[]; fields: Record<string, any> },
+): ResolvedField[] {
+  const fields: ResolvedField[] = [];
+
+  // Inject fields from each trait
+  const traits = schema.traits ?? [];
+  for (const trait of traits) {
+    const traitFields = getTraitFields(trait);
+    for (const [fieldName, fieldConfig] of Object.entries(traitFields)) {
+      fields.push({
+        name: fieldName,
+        config: fieldConfig,
+        provenance: { source: 'trait', trait },
+      });
+    }
+  }
+
+  // Add the model's own declared fields
+  for (const [fieldName, fieldConfig] of Object.entries(schema.fields)) {
+    fields.push({
+      name: fieldName,
+      config: fieldConfig,
+      provenance: { source: 'base', app },
+    });
+  }
+
+  return fields;
+}
+
+/** Append extension fields to a model, throwing on conflicts with existing fields. */
+function applyExtensionFields(
+  model: ResolvedModel,
+  extensionFields: Record<string, any>,
+  extensionApp: string,
+  target: string,
+): void {
+  for (const [fieldName, fieldConfig] of Object.entries(extensionFields)) {
+    const existing = model.fields.find((f) => f.name === fieldName);
+    if (existing) {
+      const existingSource = describeProvenance(existing);
+      throw new SchemaConflictError(
+        target,
+        fieldName,
+        existingSource,
+        `extension (${extensionApp})`,
+      );
+    }
+
+    model.fields.push({
+      name: fieldName,
+      config: fieldConfig,
+      provenance: { source: 'extension', app: extensionApp },
+    });
+  }
+}
+
+/** Produce a human-readable description of where a field came from. */
+function describeProvenance(field: ResolvedField): string {
+  switch (field.provenance.source) {
+    case 'base':
+      return `base schema (${field.provenance.app})`;
+    case 'extension':
+      return `extension (${field.provenance.app})`;
+    case 'trait':
+      return `trait (${field.provenance.trait})`;
+  }
+}

package/src/boot/traits.ts

@@ -0,0 +1,25 @@
+import type { FieldConfig } from '@rangka/shared';
+
+export interface TraitFields {
+  [fieldName: string]: FieldConfig;
+}
+
+const timestampedFields: TraitFields = {
+  created_at: { type: 'datetime' },
+  updated_at: { type: 'datetime' },
+  created_by: { type: 'link', model: 'core.user' },
+  updated_by: { type: 'link', model: 'core.user' },
+};
+
+const softDeleteFields: TraitFields = {
+  archived_at: { type: 'datetime' },
+};
+
+const traitFieldMap: Record<string, TraitFields> = {
+  timestamped: timestampedFields,
+  soft_delete: softDeleteFields,
+};
+
+export function getTraitFields(trait: string): TraitFields {
+  return traitFieldMap[trait] ?? {};
+}

package/src/boot/types.ts

@@ -0,0 +1,73 @@
+import type {
+  ModuleConfig,
+  ModelConfig,
+  ExtensionConfig,
+  HooksConfig,
+  RolesConfig,
+  JobConfig,
+  PageDefinition,
+  WidgetDefinitionMeta,
+} from '@rangka/shared';
+import type { ApiDefinition } from '../api/types.js';
+import type { ServiceDefinition } from '../services/types.js';
+import type { FixtureDefinition } from '../fixtures/types.js';
+
+export interface RangkaPackageInfo {
+  packageName: string;
+  path: string;
+  rangka: {
+    type: 'app';
+    entrypoint: string;
+  };
+}
+
+export interface DiscoveredApp {
+  packageInfo: RangkaPackageInfo;
+  config: ModuleConfig;
+  schemas: Array<{ module: string; schema: ModelConfig }>;
+  extensions: Array<{ target: string; config: ExtensionConfig }>;
+  modules?: ModuleConfig[];
+  hooks?: Array<{ model: string; hooks: HooksConfig }>;
+  roles?: Array<{ config: RolesConfig; app: string }>;
+  jobs?: Array<{ name: string; config: JobConfig }>;
+  services?: ServiceDefinition[];
+  apiDefinitions?: ApiDefinition[];
+  fixtures?: FixtureDefinition[];
+  pages?: Array<{ module: string; page: PageDefinition }>;
+  widgets?: WidgetDefinitionMeta[];
+}
+
+export interface DiscoverySource {
+  findRangkaPackages(): Promise<RangkaPackageInfo[]>;
+}
+
+export class SchemaConflictError extends Error {
+  constructor(
+    public readonly model: string,
+    public readonly field: string,
+    public readonly sourceA: string,
+    public readonly sourceB: string,
+  ) {
+    super(
+      `Schema conflict on model "${model}", field "${field}": declared by both "${sourceA}" and "${sourceB}"`,
+    );
+    this.name = 'SchemaConflictError';
+  }
+}
+
+export class MissingDependencyError extends Error {
+  constructor(
+    public readonly app: string,
+    public readonly missingDep: string,
+  ) {
+    super(`App "${app}" depends on "${missingDep}", which was not found in discovered packages`);
+    this.name = 'MissingDependencyError';
+  }
+}
+
+export class CircularDependencyError extends Error {
+  constructor(public readonly cycle: string[]) {
+    super(`Circular dependency detected: ${cycle.join(' → ')}`);
+    this.name = 'CircularDependencyError';
+  }
+}