@treenity/core 1.0.48 → 3.0.0

package/src/mod/loader.test.ts

@@ -0,0 +1,168 @@
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import { clearModRegistry, getLoadedMods, getMod, isModLoaded, loadMods, sortByDependencies } from './loader';
+import type { ModManifest } from './types';
+
+function m(name: string, deps?: string[]): ModManifest {
+  return { name, version: '1.0.0', dependencies: deps };
+}
+
+describe('sortByDependencies', () => {
+  it('returns mods in dependency order', () => {
+    const mods = [m('app', ['ui', 'auth']), m('auth', ['core']), m('ui', ['core']), m('core')];
+    const sorted = sortByDependencies(mods);
+    const names = sorted.map(m => m.name);
+
+    // core must come before auth and ui; auth and ui before app
+    assert.ok(names.indexOf('core') < names.indexOf('auth'));
+    assert.ok(names.indexOf('core') < names.indexOf('ui'));
+    assert.ok(names.indexOf('auth') < names.indexOf('app'));
+    assert.ok(names.indexOf('ui') < names.indexOf('app'));
+  });
+
+  it('handles no dependencies', () => {
+    const mods = [m('a'), m('b'), m('c')];
+    const sorted = sortByDependencies(mods);
+    assert.equal(sorted.length, 3);
+  });
+
+  it('throws on missing dependency', () => {
+    assert.throws(
+      () => sortByDependencies([m('app', ['ghost'])]),
+    );
+  });
+
+  it('throws on circular dependency (simple cycle)', () => {
+    assert.throws(
+      () => sortByDependencies([m('a', ['b']), m('b', ['a'])]),
+    );
+  });
+
+  it('throws on circular dependency (3-node cycle)', () => {
+    assert.throws(
+      () => sortByDependencies([m('a', ['b']), m('b', ['c']), m('c', ['a'])]),
+    );
+  });
+
+  it('handles diamond dependency (A→B,C; B→D; C→D)', () => {
+    const mods = [m('A', ['B', 'C']), m('B', ['D']), m('C', ['D']), m('D')];
+    const sorted = sortByDependencies(mods);
+    const names = sorted.map(m => m.name);
+
+    assert.ok(names.indexOf('D') < names.indexOf('B'));
+    assert.ok(names.indexOf('D') < names.indexOf('C'));
+    assert.ok(names.indexOf('B') < names.indexOf('A'));
+    assert.ok(names.indexOf('C') < names.indexOf('A'));
+  });
+
+  it('handles deep chain', () => {
+    const chain = Array.from({ length: 10 }, (_, i) => m(`m${i}`, i > 0 ? [`m${i - 1}`] : []));
+    const sorted = sortByDependencies(chain.reverse()); // reverse to make it harder
+    const names = sorted.map(m => m.name);
+
+    for (let i = 1; i < 10; i++) {
+      assert.ok(names.indexOf(`m${i - 1}`) < names.indexOf(`m${i}`),
+        `m${i - 1} should come before m${i}`);
+    }
+  });
+
+  it('handles single mod with self-dependency as circular', () => {
+    assert.throws(
+      () => sortByDependencies([m('narcissist', ['narcissist'])]),
+    );
+  });
+
+  it('detects partial cycle (some acyclic, some cyclic)', () => {
+    assert.throws(
+      () => sortByDependencies([m('ok'), m('a', ['b']), m('b', ['a'])]),
+    );
+  });
+});
+
+describe('loadMods', () => {
+  beforeEach(() => clearModRegistry());
+
+  it('loads mods without entry points (manifest-only)', async () => {
+    const result = await loadMods([m('simple')], 'server');
+    assert.deepEqual(result.loaded, ['simple']);
+    assert.deepEqual(result.failed, []);
+    assert.equal(isModLoaded('simple'), true);
+  });
+
+  it('tracks loaded mods in registry', async () => {
+    await loadMods([m('a'), m('b')], 'server');
+    assert.equal(getLoadedMods().length, 2);
+    assert.equal(getMod('a')?.state, 'loaded');
+    assert.equal(getMod('b')?.state, 'loaded');
+  });
+
+  it('fails if dependency not loaded', async () => {
+    const manifest: ModManifest = {
+      name: 'orphan',
+      version: '1.0.0',
+      dependencies: ['missing'],
+    };
+
+    // sortByDependencies will throw on unknown dep
+    await assert.rejects(
+      () => loadMods([manifest], 'server'),
+    );
+  });
+
+  it('fails gracefully on bad import path', async () => {
+    const manifest: ModManifest = {
+      name: 'bad-import',
+      version: '1.0.0',
+      server: './nonexistent.js',
+      packagePath: '/tmp/fake-package',
+    };
+
+    const result = await loadMods([manifest], 'server');
+    assert.equal(result.failed.length, 1);
+    assert.equal(result.failed[0].name, 'bad-import');
+    assert.equal(getMod('bad-import')?.state, 'failed');
+  });
+
+  it('clearModRegistry resets state', async () => {
+    await loadMods([m('x')], 'server');
+    assert.equal(getLoadedMods().length, 1);
+    clearModRegistry();
+    assert.equal(getLoadedMods().length, 0);
+    assert.equal(getMod('x'), undefined);
+  });
+
+  it('records loadedAt timestamp', async () => {
+    const before = Date.now();
+    await loadMods([m('timed')], 'server');
+    const after = Date.now();
+    const mod = getMod('timed')!;
+    assert.ok(mod.loadedAt! >= before && mod.loadedAt! <= after);
+  });
+
+  it('loads dependencies before dependents', async () => {
+    const order: string[] = [];
+
+    // We can't easily mock dynamic imports, but we can verify the sorted order
+    // by checking that dependencies resolve in order within the registry
+    const mods = [m('child', ['parent']), m('parent')];
+    await loadMods(mods, 'client');
+
+    const loaded = getLoadedMods();
+    const parentIdx = loaded.findIndex(m => m.manifest!.name === 'parent');
+    const childIdx = loaded.findIndex(m => m.manifest!.name === 'child');
+    assert.ok(parentIdx < childIdx, 'parent should load before child');
+  });
+
+  it('subsequent failed mod does not block already-loaded mods', async () => {
+    const mods: ModManifest[] = [
+      m('ok-mod'),
+      { name: 'fail-mod', version: '1.0.0', server: './nope.js', packagePath: '/bad' },
+    ];
+
+    const result = await loadMods(mods, 'server');
+    assert.equal(result.loaded.length, 1);
+    assert.equal(result.failed.length, 1);
+    assert.equal(isModLoaded('ok-mod'), true);
+    assert.equal(isModLoaded('fail-mod'), false);
+  });
+});

package/src/mod/loader.ts

@@ -0,0 +1,174 @@
+// Treenity Module Loader — dependency sort, load, seed
+
+import type { Tree } from '#tree';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setCurrentMod } from './tracking';
+import type { LoadedMod, ModManifest, TreenityMod } from './types';
+
+// ── Dependency sorting (Kahn's algorithm) ──
+
+export function sortByDependencies(mods: ModManifest[]): ModManifest[] {
+  const byName = new Map(mods.map(m => [m.name, m]));
+  const inDegree = new Map<string, number>();
+  const adj = new Map<string, string[]>();
+
+  for (const m of mods) {
+    if (!inDegree.has(m.name)) inDegree.set(m.name, 0);
+    if (!adj.has(m.name)) adj.set(m.name, []);
+
+    for (const dep of m.dependencies ?? []) {
+      if (!byName.has(dep)) throw new Error(`Mod "${m.name}" depends on unknown mod "${dep}"`);
+      if (!adj.has(dep)) adj.set(dep, []);
+      adj.get(dep)!.push(m.name);
+      inDegree.set(m.name, (inDegree.get(m.name) ?? 0) + 1);
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [name, deg] of inDegree) {
+    if (deg === 0) queue.push(name);
+  }
+
+  const sorted: ModManifest[] = [];
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    sorted.push(byName.get(name)!);
+    for (const next of adj.get(name) ?? []) {
+      const deg = inDegree.get(next)! - 1;
+      inDegree.set(next, deg);
+      if (deg === 0) queue.push(next);
+    }
+  }
+
+  if (sorted.length !== mods.length) {
+    const stuck = mods.filter(m => !sorted.includes(m)).map(m => m.name);
+    throw new Error(`Circular dependency among mods: ${stuck.join(', ')}`);
+  }
+
+  return sorted;
+}
+
+// ── Registry of loaded mods ──
+
+const loaded = new Map<string, LoadedMod>();
+
+export function getLoadedMods(): LoadedMod[] {
+  return [...loaded.values()];
+}
+
+export function getMod(name: string): LoadedMod | undefined {
+  return loaded.get(name);
+}
+
+export function isModLoaded(name: string): boolean {
+  return loaded.get(name)?.state === 'loaded';
+}
+
+export function clearModRegistry(): void {
+  loaded.clear();
+}
+
+// ── Loader ──
+
+export type LoadTarget = 'server' | 'client';
+
+export interface LoadResult {
+  loaded: string[];
+  failed: { name: string; error: Error }[];
+}
+
+export async function loadMods(
+  manifests: ModManifest[],
+  target: LoadTarget,
+  store?: Tree,
+): Promise<LoadResult> {
+  const sorted = sortByDependencies(manifests);
+  const result: LoadResult = { loaded: [], failed: [] };
+
+  for (const manifest of sorted) {
+    const entry: LoadedMod = { name: manifest.name, manifest, state: 'loading' };
+    loaded.set(manifest.name, entry);
+
+    try {
+      for (const dep of manifest.dependencies ?? []) {
+        if (!isModLoaded(dep)) throw new Error(`Dependency "${dep}" not loaded`);
+      }
+
+      const entryPath = target === 'server' ? manifest.server : manifest.client;
+      let mod: TreenityMod | undefined;
+
+      if (entryPath && manifest.packagePath) {
+        const fullPath = join(manifest.packagePath, entryPath);
+        setCurrentMod(manifest.name);
+        const exported = await import(fullPath);
+        setCurrentMod(null);
+        mod = exported.default as TreenityMod;
+      }
+
+      if (mod?.onLoad) await mod.onLoad();
+
+      // Seed (server-only, needs store)
+      if (target === 'server' && store) {
+        if (mod?.seed) {
+          await mod.seed(store);
+        } else if (manifest.seed && manifest.packagePath) {
+          const seedMod = await import(join(manifest.packagePath, manifest.seed));
+          await seedMod.default(store);
+        }
+      }
+
+      entry.mod = mod;
+      entry.state = 'loaded';
+      entry.loadedAt = Date.now();
+      result.loaded.push(manifest.name);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      entry.state = 'failed';
+      entry.error = error;
+      result.failed.push({ name: manifest.name, error });
+    }
+  }
+
+  return result;
+}
+
+// ── Local mod loader (side-effect imports from src/mods/) ──
+
+export async function loadLocalMods(modsDir: string, target: LoadTarget): Promise<LoadResult> {
+  const result: LoadResult = { loaded: [], failed: [] };
+  const entryFile = target === 'server' ? 'server.ts' : 'client.ts';
+  let entries: import('node:fs').Dirent[];
+
+  try {
+    entries = await readdir(modsDir, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+
+    const filePath = join(modsDir, entry.name, entryFile);
+    try { await stat(filePath); } catch { continue; }
+
+    const modEntry: LoadedMod = { name: entry.name, state: 'loading' };
+    loaded.set(entry.name, modEntry);
+
+    try {
+      setCurrentMod(entry.name);
+      await import(filePath);
+      setCurrentMod(null);
+      modEntry.state = 'loaded';
+      modEntry.loadedAt = Date.now();
+      result.loaded.push(entry.name);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      modEntry.state = 'failed';
+      modEntry.error = error;
+      result.failed.push({ name: entry.name, error });
+    }
+  }
+
+  return result;
+}