@maravilla-labs/platform 0.5.1 → 0.6.0

package/tests/policy-builder.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Unit tests for the typed policy builder (FR-7) in `src/config.ts`.
+ *
+ * Covers the emitted REL source for each helper, `.and()`/`.or()`
+ * composition, the legacy-footgun lint in `Policy.raw`, fragment
+ * expansion, and the relatesVia/group cross-validation in `defineConfig`.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  Policy,
+  ownsIt,
+  isStaff,
+  isAdmin,
+  relatesVia,
+  publicWhen,
+  fragment,
+  defineConfig,
+  assertNoLegacyShapes,
+} from '../src/config.js';
+
+describe('policy builder — emitted source', () => {
+  it('ownsIt() defaults to node.owner', () => {
+    expect(ownsIt().toString()).toBe('auth.user_id == node.owner');
+    expect(ownsIt('author').toString()).toBe('auth.user_id == node.author');
+  });
+
+  it('isStaff() defaults to staff', () => {
+    expect(isStaff().toString()).toBe("auth.roles.contains('staff')");
+    expect(isStaff('editors').toString()).toBe("auth.roles.contains('editors')");
+  });
+
+  it('isAdmin() emits auth.is_admin', () => {
+    expect(isAdmin().toString()).toBe('auth.is_admin');
+  });
+
+  it('publicWhen() defaults to node.public', () => {
+    expect(publicWhen().toString()).toBe('node.public == true');
+    expect(publicWhen('listed').toString()).toBe('node.listed == true');
+  });
+
+  it('ownsIt().or(isStaff()) composes with ||', () => {
+    expect(ownsIt().or(isStaff()).toString()).toBe(
+      "auth.user_id == node.owner || auth.roles.contains('staff')",
+    );
+  });
+
+  it('and() composes with &&', () => {
+    expect(ownsIt().and(publicWhen()).toString()).toBe(
+      'auth.user_id == node.owner && node.public == true',
+    );
+  });
+
+  it('relatesVia() with depth includes the RELATES … VIA … DEPTH clause', () => {
+    const s = relatesVia('STEWARDS', { depth: [1, 3] }).toString();
+    expect(s).toContain("RELATES auth.user_id VIA 'STEWARDS' DEPTH 1..3");
+    expect(s).toBe("node.owner RELATES auth.user_id VIA 'STEWARDS' DEPTH 1..3");
+  });
+
+  it('relatesVia() honors custom subject/object', () => {
+    expect(
+      relatesVia('GUARDIAN', { subject: 'node.child', object: 'auth.user_id' }).toString(),
+    ).toBe("auth.user_id RELATES node.child VIA 'GUARDIAN'");
+  });
+});
+
+describe('Policy.raw — legacy footgun lint', () => {
+  it('throws on bare is_admin', () => {
+    expect(() => Policy.raw('is_admin')).toThrow();
+  });
+  it('throws on auth.isAdmin', () => {
+    expect(() => Policy.raw('auth.isAdmin')).toThrow();
+  });
+  it('throws on auth.admin', () => {
+    expect(() => Policy.raw('auth.admin')).toThrow();
+  });
+  it('allows the valid auth.is_admin', () => {
+    expect(() => Policy.raw('auth.is_admin')).not.toThrow();
+  });
+  it('throws on double-quoted VIA', () => {
+    expect(() => Policy.raw('node.owner RELATES auth.user_id VIA "STEWARDS"')).toThrow();
+  });
+  it('throws on bareword VIA', () => {
+    expect(() => Policy.raw('node.owner RELATES auth.user_id VIA STEWARDS')).toThrow();
+  });
+  it('throws on path-expr VIA', () => {
+    expect(() => Policy.raw('node.owner RELATES auth.user_id VIA auth.x')).toThrow();
+  });
+  it('allows a correct single-quoted VIA', () => {
+    expect(() => Policy.raw("node.owner RELATES auth.user_id VIA 'STEWARDS'")).not.toThrow();
+  });
+
+  it('assertNoLegacyShapes is exported and matches Policy.raw', () => {
+    expect(() => assertNoLegacyShapes('is_admin')).toThrow();
+    expect(() => assertNoLegacyShapes('auth.is_admin')).not.toThrow();
+  });
+});
+
+describe('defineConfig — fragments + cross-validation', () => {
+  it('serializes Policy resource policies to strings', () => {
+    const cfg = defineConfig({
+      auth: {
+        resources: [
+          { name: 'todos', title: 'Todos', actions: ['read'], policy: ownsIt().or(isStaff()) },
+        ],
+      },
+    });
+    expect(cfg.auth!.resources![0].policy).toBe(
+      "auth.user_id == node.owner || auth.roles.contains('staff')",
+    );
+  });
+
+  it('expands fragment() references inline (parenthesized)', () => {
+    const cfg = defineConfig({
+      auth: {
+        groups: [{ name: 'staff' }],
+        fragments: { staffOrAdmin: isStaff().or(isAdmin()) },
+        resources: [
+          { name: 'todos', title: 'Todos', actions: ['read'], policy: ownsIt().or(fragment('staffOrAdmin')) },
+        ],
+      },
+    });
+    expect(cfg.auth!.resources![0].policy).toBe(
+      "auth.user_id == node.owner || (auth.roles.contains('staff') || auth.is_admin)",
+    );
+  });
+
+  it('throws on an unknown fragment reference', () => {
+    expect(() =>
+      defineConfig({
+        auth: {
+          resources: [
+            { name: 'todos', title: 'Todos', actions: ['read'], policy: ownsIt().or(fragment('missing')) },
+          ],
+        },
+      }),
+    ).toThrow(/fragment/i);
+  });
+
+  it('throws when relatesVia references an undeclared relation', () => {
+    expect(() =>
+      defineConfig({
+        auth: {
+          relations: [
+            { relation_name: 'GUARDIAN', title: 'Guardian' },
+          ],
+          resources: [
+            { name: 'records', title: 'Records', actions: ['read'], policy: relatesVia('STEWARDS') },
+          ],
+        },
+      }),
+    ).toThrow(/STEWARDS/);
+  });
+
+  it('passes when relatesVia references a declared relation', () => {
+    expect(() =>
+      defineConfig({
+        auth: {
+          relations: [{ relation_name: 'STEWARDS', title: 'Stewards' }],
+          resources: [
+            { name: 'records', title: 'Records', actions: ['read'], policy: relatesVia('STEWARDS', { depth: [1, 2] }) },
+          ],
+        },
+      }),
+    ).not.toThrow();
+  });
+
+  it('throws when a group reference is undeclared (and groups are declared)', () => {
+    expect(() =>
+      defineConfig({
+        auth: {
+          groups: [{ name: 'staff' }],
+          resources: [
+            { name: 'todos', title: 'Todos', actions: ['read'], policy: isStaff('editors') },
+          ],
+        },
+      }),
+    ).toThrow(/editors/);
+  });
+
+  it('leaves a config without auth untouched', () => {
+    const cfg = defineConfig({ database: { indexes: [{ collection: 'x', keys: { a: 1 } }] } });
+    expect(cfg.auth).toBeUndefined();
+  });
+});

package/tests/types.test-d.ts

@@ -0,0 +1,94 @@
+/**
+ * Type-level ("test-d") checks for the Phase 4 type contract. These are
+ * verified by `tsc --noEmit` (see the `typecheck:test-d` script / the
+ * tsconfig.test.json include) — there is no runtime assertion here.
+ *
+ *   - `DbDocument<T>` round-trips your fields plus `id`/`_id`.
+ *   - `insertOne` returns a `string`, NOT a `DbDocument` (@ts-expect-error).
+ *   - The global `Platform['auth']` is exactly the canonical `AuthService`.
+ *   - `db.find<T>()` / `db.findOne<T>()` return `DbDocument<T>`.
+ */
+
+import type { DbDocument, AuthService, Database } from '../src/types.js';
+import type { Platform } from '../src/types.js';
+import type { Platform as TypesPlatform, AuthService as TypesAuthService } from '@maravilla-labs/types';
+
+// ── DbDocument<T> round-trip ──────────────────────────────────────────
+
+interface Todo {
+  name: string;
+  done: boolean;
+}
+
+declare const doc: DbDocument<Todo>;
+// Own fields survive:
+const _name: string = doc.name;
+const _done: boolean = doc.done;
+// Row identity is injected:
+const _id1: string = doc.id;
+const _id2: string = doc._id;
+// Optional server timestamps:
+const _ts: string | undefined = doc._created_at;
+
+// A plain T is assignable into the doc's own-field surface.
+const _todoFields: Todo = { name: doc.name, done: doc.done };
+void _name;
+void _done;
+void _id1;
+void _id2;
+void _ts;
+void _todoFields;
+
+// ── insertOne returns a string, not a DbDocument ──────────────────────
+
+declare const db: Database;
+
+async function insertOneIsString() {
+  const inserted = await db.insertOne('todos', { name: 'x', done: false });
+  const _s: string = inserted; // ok — insertOne resolves to the id string
+  void _s;
+  // @ts-expect-error insertOne resolves to a string id, never a DbDocument
+  const _bad: DbDocument<Todo> = inserted;
+  void _bad;
+}
+void insertOneIsString;
+
+// ── find<T> / findOne<T> are DbDocument-typed ─────────────────────────
+
+async function findIsTyped() {
+  const rows = await db.find<Todo>('todos', { done: false });
+  const _row: DbDocument<Todo> = rows[0];
+  const _rowName: string = rows[0].name;
+  const one = await db.findOne<Todo>('todos', { name: 'x' });
+  const _one: DbDocument<Todo> | null = one;
+  void _row;
+  void _rowName;
+  void _one;
+}
+void findIsTyped;
+
+// ── Platform['auth'] is the canonical AuthService ─────────────────────
+
+// The global Platform's `auth` must be assignable to AuthService and back.
+declare const platformAuth: TypesPlatform['auth'];
+const _auth: AuthService = platformAuth;
+const _authBack: TypesPlatform['auth'] = {} as AuthService;
+void _auth;
+void _authBack;
+
+// The platform package re-exports the SAME AuthService as @maravilla-labs/types.
+const _sameAuth: TypesAuthService = {} as AuthService;
+const _sameAuthBack: AuthService = {} as TypesAuthService;
+void _sameAuth;
+void _sameAuthBack;
+
+// The platform package's own Platform.auth is also an AuthService.
+declare const platform2: Platform;
+const _auth2: AuthService = platform2.auth;
+void _auth2;
+
+// New FR methods are present on the canonical surface.
+type _HasAddRelation = AuthService['addRelation'];
+type _HasExplain = AuthService['explain'];
+type _HasCanMany = AuthService['canMany'];
+type _HasCreateManaged = AuthService['createManagedUser'];

package/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}