@sansavision/aurora 0.1.0-alpha.20260212.4

package/test/explain.test.ts

@@ -0,0 +1,232 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, expect, it } from "bun:test";
+
+import { runAuroraCli } from "../src";
+
+const projectRoot = join(import.meta.dir, "..");
+
+function fixturePath(name: string): string {
+  return join("test/fixtures/explain", name);
+}
+
+function readFixture(name: string): string {
+  return readFileSync(join(import.meta.dir, "fixtures/explain", name), "utf8");
+}
+
+describe("aurora explain", () => {
+  it("renders inferred behavior from a schemaVersion 1 explain report", () => {
+    const result = runAuroraCli(
+      [
+        "explain",
+        "routes/guestbook/guestbook.server.ts",
+        "--input",
+        fixturePath("module-report.v1.json"),
+      ],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("aurora explain report");
+    expect(result.stdout).toContain("module: routes/guestbook/guestbook.server.ts");
+    expect(result.stdout).toContain("query: listMessages");
+    expect(result.stdout).toContain("key: [\"routes/guestbook/guestbook.server\",\"listMessages\",\"hash(args)\"] (inferred)");
+    expect(result.stdout).toContain("action: addMessage");
+    expect(result.stdout).toContain("invalidates: [guestbook:messages] (explicit)");
+  });
+
+  it("supports json output", () => {
+    const result = runAuroraCli(
+      [
+        "explain",
+        "routes/guestbook/guestbook.server.ts",
+        "--input",
+        fixturePath("module-report.v1.json"),
+        "--format",
+        "json",
+      ],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(0);
+
+    const parsed = JSON.parse(result.stdout ?? "{}") as {
+      mode?: string;
+      schemaVersion?: number;
+      module?: string;
+      queries?: Array<{ name?: string }>;
+      actions?: Array<{ name?: string }>;
+      warnings?: string[];
+      inlineHints?: Array<{ kind?: string; symbol?: string; label?: string }>;
+    };
+
+    expect(parsed.mode).toBe("explain");
+    expect(parsed.schemaVersion).toBe(1);
+    expect(parsed.module).toBe("routes/guestbook/guestbook.server.ts");
+    expect(parsed.queries?.[0]?.name).toBe("listMessages");
+    expect(parsed.actions?.[0]?.name).toBe("addMessage");
+    expect(parsed.warnings).toEqual([]);
+    expect(parsed.inlineHints).toEqual([]);
+  });
+
+  it("includes inline hints when module source is available", () => {
+    const cwd = createTempWorkspace("aurora-explain-inline-hints");
+    const modulePath = join(cwd, "routes", "guestbook", "guestbook.server.ts");
+    mkdirSync(join(cwd, "routes", "guestbook"), { recursive: true });
+    writeFileSync(
+      modulePath,
+      [
+        'export const runtime = "edge";',
+        'export const auth = "user";',
+        "",
+        "export const listMessages = defineQuery({});",
+        "export const addMessage = defineAction({});",
+      ].join("\n"),
+      "utf8",
+    );
+
+    writeFileSync(
+      join(cwd, "module-report.v1.json"),
+      readFixture("module-report.v1.json"),
+      "utf8",
+    );
+
+    const result = runAuroraCli(
+      [
+        "explain",
+        "routes/guestbook/guestbook.server.ts",
+        "--input",
+        "module-report.v1.json",
+        "--format",
+        "json",
+      ],
+      { cwd },
+    );
+
+    expect(result.exitCode).toBe(0);
+
+    const parsed = JSON.parse(result.stdout ?? "{}") as {
+      inlineHints?: Array<{ kind?: string; label?: string; symbol?: string }>;
+    };
+
+    expect((parsed.inlineHints ?? []).length >= 7).toBe(true);
+    expect(parsed.inlineHints?.some((hint) => hint.kind === "runtime" && hint.label === "runtime: edge")).toBe(true);
+    expect(parsed.inlineHints?.some((hint) => hint.kind === "key" && hint.symbol === "listMessages")).toBe(true);
+    expect(parsed.inlineHints?.some((hint) => hint.kind === "invalidation" && hint.symbol === "addMessage")).toBe(true);
+  });
+
+  it("reports module mismatch warning when requested module differs from snapshot module", () => {
+    const result = runAuroraCli(
+      [
+        "explain",
+        "routes/chat/chat.server.ts",
+        "--input",
+        fixturePath("module-report.v1.json"),
+        "--format",
+        "json",
+      ],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(0);
+
+    const parsed = JSON.parse(result.stdout ?? "{}") as {
+      warnings?: string[];
+    };
+
+    expect(parsed.warnings?.[0]).toContain("snapshot module");
+    expect(parsed.warnings?.[0]).toContain("requested module");
+  });
+
+  it("requires a module path", () => {
+    const result = runAuroraCli(["explain"], { cwd: projectRoot });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("module path is required");
+  });
+
+  it("rejects unknown explain options", () => {
+    const result = runAuroraCli(
+      [
+        "explain",
+        "routes/guestbook/guestbook.server.ts",
+        "--unknown",
+      ],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("unknown option '--unknown'");
+  });
+
+  it("returns readable errors for invalid json", () => {
+    const inputPath = fixturePath("invalid.json");
+    const result = runAuroraCli(
+      [
+        "explain",
+        "routes/guestbook/guestbook.server.ts",
+        "--input",
+        inputPath,
+      ],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain(`aurora explain: invalid json input at ${inputPath}`);
+  });
+
+  it("fails explain report parsing for unsupported schema versions", () => {
+    const result = runAuroraCli(
+      [
+        "explain",
+        "routes/guestbook/guestbook.server.ts",
+        "--input",
+        fixturePath("module-report.unsupported-version.v2.json"),
+      ],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("unsupported schemaVersion 2; expected 1");
+  });
+
+  it("uses the default explain snapshot path when --input is omitted", () => {
+    const cwd = createTempWorkspace("aurora-explain-default-input");
+    mkdirSync(join(cwd, ".aurora", "explain"), { recursive: true });
+    writeFileSync(
+      join(cwd, ".aurora", "explain", "routes__guestbook__guestbook.server.ts.explain.v1.json"),
+      readFixture("module-report.v1.json"),
+      "utf8",
+    );
+
+    const result = runAuroraCli(["explain", "routes/guestbook/guestbook.server.ts"], {
+      cwd,
+    });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain(
+      "input: .aurora/explain/routes__guestbook__guestbook.server.ts.explain.v1.json",
+    );
+  });
+
+  it("returns a clear error when the explain snapshot file does not exist", () => {
+    const cwd = createTempWorkspace("aurora-explain-missing-snapshot");
+
+    const result = runAuroraCli(["explain", "routes/guestbook/guestbook.server.ts"], {
+      cwd,
+    });
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain(
+      "aurora explain: unable to read input at .aurora/explain/routes__guestbook__guestbook.server.ts.explain.v1.json",
+    );
+  });
+});
+
+function createTempWorkspace(prefix: string): string {
+  const unique = `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`;
+  const cwd = join("/tmp", unique);
+  mkdirSync(cwd, { recursive: true });
+  return cwd;
+}

package/test/feature-skeleton.test.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, expect, it } from "bun:test";
+
+const templateRoot = join(import.meta.dir, "../templates/feature-skeleton");
+
+describe("feature skeleton template assets", () => {
+  it("includes required ui/query/action/realtime scaffold files", () => {
+    const required = [
+      "README.md",
+      "template.manifest.json",
+      "index.ts",
+      "ui/FeatureView.client.tsx",
+      "queries/listFeature.server.ts",
+      "actions/createFeature.action.server.ts",
+      "realtime/useFeatureRealtime.client.ts",
+    ];
+
+    for (const relativePath of required) {
+      expect(existsSync(join(templateRoot, relativePath))).toBe(true);
+    }
+  });
+
+  it("keeps placeholder contract tokens for future generator wiring", () => {
+    const placeholderFiles = [
+      "ui/FeatureView.client.tsx",
+      "queries/listFeature.server.ts",
+      "actions/createFeature.action.server.ts",
+      "realtime/useFeatureRealtime.client.ts",
+      "index.ts",
+    ];
+
+    for (const relativePath of placeholderFiles) {
+      const source = readFileSync(join(templateRoot, relativePath), "utf8");
+      expect(source).toContain("__AURORA_FEATURE_NAME__");
+      expect(source).toContain("__AURORA_FEATURE_SLUG__");
+    }
+  });
+
+  it("keeps manifest module list aligned with scaffold files", () => {
+    const manifestRaw = readFileSync(join(templateRoot, "template.manifest.json"), "utf8");
+    const manifest = JSON.parse(manifestRaw) as { modules?: string[] };
+
+    expect(Array.isArray(manifest.modules)).toBe(true);
+    const modules = manifest.modules ?? [];
+    expect(modules.length > 0).toBe(true);
+
+    for (const modulePath of modules) {
+      expect(existsSync(join(templateRoot, modulePath))).toBe(true);
+    }
+  });
+});

package/test/fixtures/analyze/cache-input.invalid.json

@@ -0,0 +1 @@
+{ "schemaVersion": 1, "entries": [ { "hash": "users:u1" } 

package/test/fixtures/analyze/cache-input.missing-keyhash.v1.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "entries": [
+    {
+      "labels": ["users", "tenant:a"],
+      "sizeBytes": 64,
+      "data": { "id": "u1" }
+    }
+  ]
+}

package/test/fixtures/analyze/cache-input.unsupported-version.v2.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 2,
+  "entries": [
+    {
+      "hash": "users:u1",
+      "labels": ["users"],
+      "sizeBytes": 64
+    }
+  ]
+}

package/test/fixtures/analyze/cache-input.v1.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "entries": [
+    {
+      "hash": "users:u1",
+      "labels": ["users", "tenant:a"],
+      "payload": { "id": "u1", "name": "A" },
+      "queryKey": ["users.byId", { "id": "u1" }],
+      "stale": true
+    }
+  ]
+}

package/test/fixtures/analyze/compiler-manifest/manifest.json

@@ -0,0 +1,11 @@
+{
+  "routes": [
+    { "id": "home", "path": "/" },
+    { "id": "about", "path": "/about" },
+    { "id": "settings", "path": "/settings" }
+  ],
+  "chunks": [
+    { "id": "home-chunk", "file": "home.js" },
+    { "id": "shared-chunk", "file": "shared.js" }
+  ]
+}

package/test/fixtures/analyze/guardrails-input.unsupported-version.v2.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 2,
+  "queries": []
+}

package/test/fixtures/analyze/guardrails-input.v1.json

@@ -0,0 +1,49 @@
+{
+  "schemaVersion": 1,
+  "queries": [
+    {
+      "name": "users.list",
+      "returnsArray": true,
+      "hasLimit": false,
+      "file": "routes/users/page.tsx",
+      "line": 12
+    }
+  ],
+  "payloads": [
+    {
+      "name": "users.export",
+      "bytes": 6200000,
+      "warnBytes": 1000000,
+      "errorBytes": 5000000,
+      "surface": "loader",
+      "file": "routes/users/export.server.ts",
+      "line": 24
+    }
+  ],
+  "nPlusOne": [
+    {
+      "file": "routes/users/page.tsx",
+      "line": 33,
+      "parentQuery": "users.list",
+      "childQuery": "teams.byUser",
+      "parentRows": 20,
+      "childCalls": 44
+    }
+  ],
+  "staleClosures": [
+    {
+      "file": "routes/users/page.tsx",
+      "line": 49,
+      "signal": "filters",
+      "context": "setInterval",
+      "stale": true
+    }
+  ],
+  "bundles": [
+    {
+      "route": "/users",
+      "bytes": 260000,
+      "budgetBytes": 180000
+    }
+  ]
+}

package/test/fixtures/analyze/query-input.invalid-cache-status.v1.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "samples": [
+    {
+      "name": "users.byId",
+      "key": "users:u1",
+      "ms": 12,
+      "cache": "unknown"
+    }
+  ]
+}

package/test/fixtures/analyze/query-input.unsupported-version.v2.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 2,
+  "samples": [
+    {
+      "name": "users.byId",
+      "key": "users:u1",
+      "ms": 12,
+      "cache": "hit"
+    }
+  ]
+}

package/test/fixtures/analyze/query-input.v1.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "samples": [
+    {
+      "name": "users.byId",
+      "key": "users:u1",
+      "ms": 15,
+      "cache": "hit",
+      "merged": true
+    },
+    {
+      "name": "teams.list",
+      "key": "teams:list",
+      "ms": 55,
+      "cache": "miss"
+    }
+  ]
+}

package/test/fixtures/analyze/realtime-input.missing-lag-p95.v1.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "rx": 50,
+  "tx": 48,
+  "dropped": 2,
+  "deliveredRps": 10,
+  "dropReasons": {
+    "stale": 2
+  }
+}

package/test/fixtures/analyze/realtime-input.unsupported-version.v2.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 2,
+  "rx": 10,
+  "tx": 9,
+  "dropped": 1,
+  "deliveredRps": 3,
+  "lagP95Ms": 120
+}

package/test/fixtures/analyze/realtime-input.v1.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "rx": 100,
+  "tx": 94,
+  "dropped": 6,
+  "deliveredRps": 15,
+  "lagP95Ms": 260,
+  "dropReasons": {
+    "stale": 4,
+    "duplicate": 2
+  }
+}

package/test/fixtures/cache-inspector/cache-input.v1.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "entries": [
+    {
+      "hash": "users:u1",
+      "labels": ["users", "user:u1"],
+      "sizeBytes": 128,
+      "stale": false
+    },
+    {
+      "hash": "users:u2",
+      "labels": ["users", "user:u2"],
+      "sizeBytes": 256,
+      "stale": true
+    },
+    {
+      "hash": "teams:list",
+      "labels": ["teams"],
+      "sizeBytes": 64,
+      "stale": false
+    }
+  ]
+}

package/test/fixtures/cache-inspector/invalid.json

@@ -0,0 +1 @@
+{ "version": 1, "entries": [ { "key": "users:u1" } 

package/test/fixtures/cache-inspector/snapshot.v1.json

@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "generatedAt": "2026-02-10T00:00:00.000Z",
+  "entries": [
+    {
+      "key": "users:u1",
+      "value": {
+        "id": "u1",
+        "name": "Ada"
+      },
+      "tags": ["users", "user:u1"],
+      "createdAt": 1707523200000
+    },
+    {
+      "key": "teams:list",
+      "value": [
+        { "id": "t1" },
+        { "id": "t2" }
+      ],
+      "tags": ["teams", "dashboard"],
+      "createdAt": 1707523201000,
+      "expiresAt": 1
+    },
+    {
+      "key": "metrics:dashboard",
+      "value": {
+        "panels": 12,
+        "updatedAt": "2026-02-10T00:00:00.000Z"
+      },
+      "tags": ["metrics", "dashboard"],
+      "createdAt": 1707523202000
+    }
+  ]
+}

package/test/fixtures/cache-inspector/unsupported-version.v2.json

@@ -0,0 +1,13 @@
+{
+  "version": 2,
+  "entries": [
+    {
+      "key": "users:u1",
+      "value": {
+        "id": "u1"
+      },
+      "tags": ["users"],
+      "createdAt": 1707523200000
+    }
+  ]
+}

package/test/fixtures/devtools/healthy.v1.json

@@ -0,0 +1,130 @@
+{
+  "schemaVersion": 1,
+  "explain": {
+    "module": "routes/guestbook/guestbook.server.ts",
+    "queries": [
+      {
+        "name": "listMessages",
+        "auth": { "value": "user" },
+        "realtime": { "value": "subscribed via tags" }
+      },
+      {
+        "name": "listMembers",
+        "auth": "admin",
+        "realtime": "none"
+      }
+    ],
+    "actions": [
+      {
+        "name": "addMessage",
+        "auth": { "value": "user" }
+      },
+      {
+        "name": "archiveMessage",
+        "auth": "admin"
+      }
+    ],
+    "warnings": []
+  },
+  "waterfall": {
+    "requestId": "req-healthy",
+    "operations": [
+      {
+        "name": "middleware.auth",
+        "kind": "middleware",
+        "startMs": 0,
+        "durationMs": 2,
+        "blocking": false
+      },
+      {
+        "name": "route.match",
+        "kind": "routing",
+        "startMs": 0,
+        "durationMs": 3,
+        "blocking": false
+      },
+      {
+        "name": "listMessages",
+        "kind": "query",
+        "startMs": 3,
+        "durationMs": 25,
+        "blocking": true
+      },
+      {
+        "name": "listMembers",
+        "kind": "query",
+        "startMs": 4,
+        "durationMs": 20,
+        "blocking": true
+      },
+      {
+        "name": "render",
+        "kind": "render",
+        "startMs": 29,
+        "durationMs": 8,
+        "blocking": true
+      }
+    ],
+    "phases": [
+      {
+        "name": "routing",
+        "durationMs": 3
+      },
+      {
+        "name": "data",
+        "durationMs": 25
+      },
+      {
+        "name": "render",
+        "durationMs": 8
+      }
+    ]
+  },
+  "performance": {
+    "routes": [
+      {
+        "route": "/",
+        "jsBytes": 42000,
+        "payloadBytes": 1200,
+        "lcpMs": 210
+      },
+      {
+        "route": "/guestbook",
+        "jsBytes": 58000,
+        "payloadBytes": 3200,
+        "lcpMs": 310
+      }
+    ]
+  },
+  "realtime": {
+    "connectionState": "connected",
+    "eventsPerSecond": 24.5,
+    "lagP95Ms": 140,
+    "droppedRatio": 0.012,
+    "subscriptions": [
+      {
+        "tag": "guestbook:messages",
+        "channel": "guestbook.ws",
+        "state": "active",
+        "authScope": "user"
+      },
+      {
+        "tag": "guestbook:admins",
+        "channel": "guestbook.ws",
+        "state": "active",
+        "authScope": "admin"
+      }
+    ]
+  },
+  "auth": {
+    "sessionStatus": "active",
+    "routeAuth": "user",
+    "userId": "u_123",
+    "role": "user",
+    "permissions": [
+      "guestbook:read",
+      "guestbook:write"
+    ],
+    "tokenExpiresInSec": 3600
+  }
+}

package/test/fixtures/devtools/invalid.json

@@ -0,0 +1 @@
+{ "schemaVersion": 1,