@rangka/core 0.0.1

package/src/boot/__tests__/page-utils.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect } from 'vitest';
+import { extractSourceModels, validatePageSources } from '../page-utils.js';
+import type { PageDefinition } from '@rangka/shared';
+
+describe('extractSourceModels', () => {
+  it('extracts models from data widget source', () => {
+    const page: PageDefinition = {
+      key: 'sales.orders',
+      label: 'Orders',
+      type: 'collection',
+      body: [
+        {
+          type: 'data',
+          source: { model: 'sales.order' },
+          children: [{ type: 'text', bind: { field: 'name' } }],
+        },
+      ],
+    };
+
+    const models = extractSourceModels(page);
+    expect(models).toContain('sales.order');
+    expect(models).toHaveLength(1);
+  });
+
+  it('extracts models from nested data widgets', () => {
+    const page: PageDefinition = {
+      key: 'sales.orders',
+      label: 'Orders',
+      type: 'collection',
+      body: [
+        {
+          type: 'data',
+          source: { model: 'sales.order' },
+          children: [
+            {
+              type: 'data',
+              source: { model: 'sales.order_item' },
+              children: [{ type: 'text', bind: { field: 'quantity' } }],
+            },
+          ],
+        },
+      ],
+    };
+
+    const models = extractSourceModels(page);
+    expect(models).toContain('sales.order');
+    expect(models).toContain('sales.order_item');
+    expect(models).toHaveLength(2);
+  });
+
+  it('extracts models from table with model binding', () => {
+    const page: PageDefinition = {
+      key: 'sales.orders',
+      label: 'Orders',
+      type: 'collection',
+      body: [
+        {
+          type: 'table',
+          bind: { model: { name: 'sales.invoice' } },
+          children: [{ type: 'column', bind: { field: 'name' } }],
+        },
+      ],
+    };
+
+    const models = extractSourceModels(page);
+    expect(models).toContain('sales.invoice');
+    expect(models).toHaveLength(1);
+  });
+
+  it('extracts models from multiple siblings', () => {
+    const page: PageDefinition = {
+      key: 'sales.orders',
+      label: 'Orders',
+      type: 'collection',
+      body: [
+        { type: 'data', source: { model: 'sales.order' }, children: [] },
+        { type: 'data', source: { model: 'contacts.contact' }, children: [] },
+      ],
+    };
+
+    const models = extractSourceModels(page);
+    expect(models).toContain('sales.order');
+    expect(models).toContain('contacts.contact');
+    expect(models).toHaveLength(2);
+  });
+
+  it('returns empty for body without data sources', () => {
+    const page: PageDefinition = {
+      key: 'sales.dashboard',
+      label: 'Dashboard',
+      type: 'dashboard',
+      body: [
+        { type: 'text', props: { content: 'Hello' } },
+        { type: 'button', props: { label: 'Click' } },
+      ],
+    };
+
+    const models = extractSourceModels(page);
+    expect(models).toHaveLength(0);
+  });
+
+  it('deduplicates repeated model references', () => {
+    const page: PageDefinition = {
+      key: 'sales.orders',
+      label: 'Orders',
+      type: 'collection',
+      body: [
+        { type: 'data', source: { model: 'sales.order' }, children: [] },
+        { type: 'table', bind: { model: { name: 'sales.order' } }, children: [] },
+      ],
+    };
+
+    const models = extractSourceModels(page);
+    expect(models).toEqual(['sales.order']);
+  });
+});
+
+describe('validatePageSources', () => {
+  const knownModels = new Set(['sales.order', 'sales.customer', 'contacts.contact']);
+
+  it('catches unresolved models in data widget', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: {
+          key: 'sales.broken',
+          label: 'Broken',
+          type: 'collection',
+          body: [
+            {
+              type: 'data',
+              source: { model: 'sales.nonexistent' },
+              children: [],
+            },
+          ],
+        },
+      },
+    ];
+
+    const warnings = validatePageSources(pages, knownModels);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].pageKey).toBe('sales.broken');
+    expect(warnings[0].location).toBe('body[0]');
+    expect(warnings[0].message).toContain('sales.nonexistent');
+  });
+
+  it('catches unresolved models in nested children', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: {
+          key: 'sales.nested',
+          label: 'Nested',
+          type: 'collection',
+          body: [
+            {
+              type: 'data',
+              source: { model: 'sales.order' },
+              children: [
+                {
+                  type: 'data',
+                  source: { model: 'sales.ghost' },
+                  children: [],
+                },
+              ],
+            },
+          ],
+        },
+      },
+    ];
+
+    const warnings = validatePageSources(pages, knownModels);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].location).toBe('body[0].children[0]');
+    expect(warnings[0].message).toContain('sales.ghost');
+  });
+
+  it('catches unresolved models in table bind.model', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: {
+          key: 'sales.table',
+          label: 'Table',
+          type: 'collection',
+          body: [
+            {
+              type: 'table',
+              bind: { model: { name: 'sales.missing' } },
+              children: [],
+            },
+          ],
+        },
+      },
+    ];
+
+    const warnings = validatePageSources(pages, knownModels);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].location).toBe('body[0]');
+    expect(warnings[0].message).toContain('sales.missing');
+  });
+
+  it('passes when all models exist', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: {
+          key: 'sales.orders',
+          label: 'Orders',
+          type: 'collection',
+          body: [
+            {
+              type: 'data',
+              source: { model: 'sales.order' },
+              children: [{ type: 'text', bind: { field: 'name' } }],
+            },
+          ],
+        },
+      },
+    ];
+
+    const warnings = validatePageSources(pages, knownModels);
+    expect(warnings).toHaveLength(0);
+  });
+});

package/src/boot/__tests__/project-scanner.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import * as path from 'node:path';
+import { ProjectScanner } from '../project-scanner.js';
+
+const FIXTURE_ROOT = path.resolve(__dirname, '../../../../../tests/fixtures/basic-app');
+
+describe('ProjectScanner', () => {
+  it('discovers modules from modules/ directory', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.app.schemas.length).toBeGreaterThan(0);
+    const modules = new Set(result.app.schemas.map((s) => s.module));
+    expect(modules.has('sales')).toBe(true);
+  });
+
+  it('discovers model schemas from flat files', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    const schemaNames = result.app.schemas.map((s) => s.schema.name);
+    expect(schemaNames).toContain('customer');
+    expect(schemaNames).toContain('invoice');
+  });
+
+  it('loads hooks from hooks/ directory', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.app.hooks).toBeDefined();
+    const invoiceHooks = result.app.hooks!.find((h) => h.model === 'sales.invoice');
+    expect(invoiceHooks).toBeDefined();
+    expect(invoiceHooks!.hooks.validate).toBeTypeOf('function');
+  });
+
+  it('loads roles from per-module roles.ts', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.app.roles).toBeDefined();
+    expect(result.app.roles!.length).toBeGreaterThan(0);
+    const salesRoles = result.app.roles!.find((r) => r.app === 'sales');
+    expect(salesRoles).toBeDefined();
+    expect(salesRoles!.config['Sales User']).toBeDefined();
+    expect(salesRoles!.config['Sales Manager']).toBeDefined();
+  });
+
+  it('loads rangka.config.ts', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.rangkaConfig).toBeDefined();
+    expect(result.rangkaConfig.database.dialect).toBe('pg');
+    expect(result.rangkaConfig.database.host).toBe('localhost');
+    expect(result.rangkaConfig.database.port).toBe(5433);
+    expect(result.rangkaConfig.database.database).toBe('rangka_test');
+  });
+
+  it('returns empty extensions when extensions/ dir does not exist', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.app.extensions).toEqual([]);
+  });
+
+  it('throws when rangka.config.ts is missing', async () => {
+    const scanner = new ProjectScanner('/tmp/nonexistent-rangka-project');
+    await expect(scanner.scan()).rejects.toThrow('No rangka.config.ts found');
+  });
+
+  it('produces DiscoveredApp compatible with boot()', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.app.packageInfo.path).toBe(FIXTURE_ROOT);
+    expect(result.app.packageInfo.rangka.type).toBe('app');
+  });
+
+  it('discovers pages from pages/ directory', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.app.pages).toBeDefined();
+    const pageKeys = result.app.pages!.map((p) => p.page.key);
+    expect(pageKeys).toContain('sales.customers');
+    expect(pageKeys).toContain('sales.orders');
+  });
+});

package/src/boot/dependency-sort.ts

@@ -0,0 +1,82 @@
+import type { ModuleConfig } from '@rangka/shared';
+import { CircularDependencyError, MissingDependencyError } from './types.js';
+
+// Topological sort of app modules by their declared dependencies.
+// Core is always first; remaining apps are sorted so dependencies load before dependents.
+export function dependencySort(apps: ModuleConfig[]): ModuleConfig[] {
+  const appsByName = new Map<string, ModuleConfig>(apps.map((app) => [app.name, app]));
+
+  const coreApp = appsByName.get('core');
+  if (!coreApp) {
+    throw new Error('Core app must be present in the app list');
+  }
+
+  const nonCoreApps = apps.filter((a) => a.name !== 'core');
+  validateDependenciesExist(nonCoreApps, appsByName);
+
+  const sorted = topologicalSort(nonCoreApps, appsByName);
+  return [coreApp, ...sorted];
+}
+
+function validateDependenciesExist(
+  apps: ModuleConfig[],
+  appsByName: Map<string, ModuleConfig>,
+): void {
+  for (const app of apps) {
+    for (const dep of app.depends ?? []) {
+      if (dep !== 'core' && !appsByName.has(dep)) {
+        throw new MissingDependencyError(app.name, dep);
+      }
+    }
+  }
+}
+
+// Kahn's algorithm — processes apps with no remaining dependencies first.
+function topologicalSort(
+  apps: ModuleConfig[],
+  appsByName: Map<string, ModuleConfig>,
+): ModuleConfig[] {
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+
+  for (const app of apps) {
+    inDegree.set(app.name, 0);
+    dependents.set(app.name, []);
+  }
+
+  for (const app of apps) {
+    for (const dep of app.depends ?? []) {
+      if (dep === 'core') continue;
+      dependents.get(dep)!.push(app.name);
+      inDegree.set(app.name, inDegree.get(app.name)! + 1);
+    }
+  }
+
+  const ready = apps
+    .filter((app) => inDegree.get(app.name) === 0)
+    .map((app) => app.name)
+    .sort();
+
+  const sorted: ModuleConfig[] = [];
+
+  while (ready.length > 0) {
+    const current = ready.shift()!;
+    sorted.push(appsByName.get(current)!);
+
+    for (const dependent of dependents.get(current) ?? []) {
+      const remaining = inDegree.get(dependent)! - 1;
+      inDegree.set(dependent, remaining);
+      if (remaining === 0) {
+        ready.push(dependent);
+        ready.sort();
+      }
+    }
+  }
+
+  if (sorted.length < apps.length) {
+    const unsorted = apps.filter((a) => !sorted.includes(a)).map((a) => a.name);
+    throw new CircularDependencyError(unsorted);
+  }
+
+  return sorted;
+}

package/src/boot/discovery.ts

@@ -0,0 +1,85 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { DiscoverySource, RangkaPackageInfo } from './types.js';
+
+// Scans node_modules for packages that declare themselves as rangka apps in package.json.
+export class NodeModulesDiscoverySource implements DiscoverySource {
+  constructor(private readonly projectRoot: string) {}
+
+  async findRangkaPackages(): Promise<RangkaPackageInfo[]> {
+    const nodeModulesPath = path.join(this.projectRoot, 'node_modules');
+    const packageDirs = await this.listPackageDirs(nodeModulesPath);
+
+    const results: RangkaPackageInfo[] = [];
+    for (const { dirPath, packageName } of packageDirs) {
+      const info = await this.tryReadRangkaConfig(dirPath, packageName);
+      if (info) results.push(info);
+    }
+    return results;
+  }
+
+  // Lists all package directories, expanding scoped (@org/pkg) folders.
+  private async listPackageDirs(
+    nodeModulesPath: string,
+  ): Promise<{ dirPath: string; packageName: string }[]> {
+    const entries = await fs.readdir(nodeModulesPath, { withFileTypes: true });
+    const dirs: { dirPath: string; packageName: string }[] = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+
+      if (entry.name.startsWith('@')) {
+        const scopePath = path.join(nodeModulesPath, entry.name);
+        const scopedEntries = await fs.readdir(scopePath, { withFileTypes: true });
+        for (const scoped of scopedEntries) {
+          if (!scoped.isDirectory()) continue;
+          dirs.push({
+            dirPath: path.join(scopePath, scoped.name),
+            packageName: `${entry.name}/${scoped.name}`,
+          });
+        }
+      } else {
+        dirs.push({
+          dirPath: path.join(nodeModulesPath, entry.name),
+          packageName: entry.name,
+        });
+      }
+    }
+
+    return dirs;
+  }
+
+  // Reads package.json and returns info only if it declares rangka.type === 'app'.
+  private async tryReadRangkaConfig(
+    dirPath: string,
+    packageName: string,
+  ): Promise<RangkaPackageInfo | null> {
+    try {
+      const content = await fs.readFile(path.join(dirPath, 'package.json'), 'utf-8');
+      const pkgJson = JSON.parse(content);
+
+      if (pkgJson.rangka?.type === 'app') {
+        return {
+          packageName,
+          path: dirPath,
+          rangka: {
+            type: pkgJson.rangka.type,
+            entrypoint: pkgJson.rangka.entrypoint || './app.ts',
+          },
+        };
+      }
+    } catch {
+      // package.json doesn't exist or is unreadable — skip
+    }
+    return null;
+  }
+}
+
+// In-memory discovery source for testing.
+export class MemoryDiscoverySource implements DiscoverySource {
+  constructor(private readonly packages: RangkaPackageInfo[]) {}
+
+  async findRangkaPackages(): Promise<RangkaPackageInfo[]> {
+    return this.packages;
+  }
+}