@rangka/core 0.1.1 → 0.1.3

package/src/boot/project-scanner.ts

@@ -1,397 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

@@ -1,125 +0,0 @@
-/* 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

@@ -1,25 +0,0 @@
-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

@@ -1,73 +0,0 @@
-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';
-  }
-}