gorsee 0.2.3 → 0.2.5

package/dist-pkg/compiler/backends/register.js

@@ -0,0 +1,22 @@
+import { createTypeScriptModuleAnalysisBackend } from "../analysis-backend.js";
+import { registerModuleAnalysisBackend } from "../module-analysis.js";
+import {
+  createExperimentalOxcModuleAnalysisBackend,
+  EXPERIMENTAL_OXC_BACKEND_NAME
+} from "./experimental-oxc.js";
+import {
+  createOxcModuleAnalysisBackend,
+  OXC_BACKEND_NAME
+} from "./oxc.js";
+export function registerBuiltInCompilerBackends(options = {}) {
+  const registered = [], fallbackBackend = options.fallbackBackend ?? createTypeScriptModuleAnalysisBackend();
+  if (options.includeExperimentalOxc) {
+    registerModuleAnalysisBackend(createExperimentalOxcModuleAnalysisBackend({ fallback: fallbackBackend }));
+    registered.push(EXPERIMENTAL_OXC_BACKEND_NAME);
+  }
+  if (options.includeOxc) {
+    registerModuleAnalysisBackend(createOxcModuleAnalysisBackend({ fallback: fallbackBackend }));
+    registered.push(OXC_BACKEND_NAME);
+  }
+  return registered;
+}

package/dist-pkg/compiler/fixtures.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleAnalysisParityFixture } from "./parity.js";
+export declare const MODULE_ANALYSIS_FIXTURES: ModuleAnalysisParityFixture[];

package/dist-pkg/compiler/fixtures.js

@@ -0,0 +1,118 @@
+export const MODULE_ANALYSIS_FIXTURES = [
+  {
+    filePath: "routes/index.tsx",
+    content: `
+      /** Home */
+      import { Head } from "gorsee/client"
+      export const meta = { title: "Home", secure: true }
+      export const prerender = true
+      export async function loader() { return { ok: true } }
+      export default function Page() { return <main>{String(!!Head)}</main> }
+    `
+  },
+  {
+    filePath: "routes/api/users.ts",
+    content: `
+      import type { Context } from "gorsee/server"
+      export async function GET(_ctx: Context) { return new Response("ok") }
+    `
+  },
+  {
+    filePath: "routes/dashboard.tsx",
+    content: `
+      /** Dashboard */
+      import { createSignal } from "gorsee/client"
+      export const meta = { area: "ops", tags: ["team"] }
+      export default function Dashboard() {
+        const [count] = createSignal(1)
+        return <main>{count()}</main>
+      }
+    `
+  },
+  {
+    filePath: "routes/admin.tsx",
+    content: `
+      /** Admin */
+      import Layout from "../shared/layout"
+      import * as auth from "gorsee/server"
+      import { Head, Link } from "gorsee/client"
+
+      export const meta = {
+        area: "admin",
+        secure: true,
+        tags: ["ops", "internal"],
+        nested: { feature: "audit" },
+      }
+
+      export default class AdminPage {
+        render() {
+          return <main>{String(!!Layout && !!auth && !!Head && !!Link)}</main>
+        }
+      }
+    `
+  },
+  {
+    filePath: "routes/settings.tsx",
+    content: `
+      /** Settings */
+      import type { Context } from "gorsee/server"
+      import { createSignal } from "gorsee/client"
+
+      export const meta = {
+        title: "Settings",
+        sections: ["profile", "security"],
+        flags: { beta: false, public: null },
+      }
+
+      export async function loader(_ctx: Context) {
+        return { section: "profile" }
+      }
+
+      export default function SettingsPage() {
+        const [tab] = createSignal("profile")
+        return <main>{tab()}</main>
+      }
+    `
+  },
+  {
+    filePath: "routes/docs/[...parts].tsx",
+    content: `
+      /** Docs */
+      import type { Context } from "gorsee/server"
+
+      export const meta = {
+        title: "Docs",
+        sections: ["intro", "advanced"],
+        flags: { public: true, beta: false, note: null },
+      }
+
+      export async function loader(_ctx: Context) {
+        return { parts: ["intro"] }
+      }
+
+      export default function DocsPage() {
+        return <main>docs</main>
+      }
+    `
+  },
+  {
+    filePath: "routes/reports.tsx",
+    content: `
+      /** Reports */
+      import { Head } from "gorsee/client"
+      import * as serverApi from "gorsee/server"
+
+      export const meta = {
+        title: "Reports",
+        filters: ["daily", "weekly"],
+        nested: { view: "table", badges: [1, 2] },
+      }
+
+      export const prerender = false
+
+      export default function ReportsPage() {
+        return <main>{String(!!Head && !!serverApi)}</main>
+      }
+    `
+  }
+];

package/dist-pkg/compiler/init.d.ts

@@ -0,0 +1 @@
+export declare function initializeCompilerBackends(env?: NodeJS.ProcessEnv): import("./analysis-backend.js").ModuleAnalysisBackend;

package/dist-pkg/compiler/init.js

@@ -0,0 +1,6 @@
+import { registerBuiltInCompilerBackends } from "./backends/register.js";
+import { configureModuleAnalysisBackend } from "./module-analysis.js";
+export function initializeCompilerBackends(env = process.env) {
+  registerBuiltInCompilerBackends({ includeExperimentalOxc: !0, includeOxc: !0 });
+  return configureModuleAnalysisBackend(env);
+}

package/dist-pkg/compiler/module-analysis.d.ts

@@ -0,0 +1,13 @@
+import { type ModuleAnalysisBackend, type ModuleAnalysisFacts, type ModuleImportFact } from "./analysis-backend.js";
+export declare const GORSEE_COMPILER_BACKEND_ENV = "GORSEE_COMPILER_BACKEND";
+export declare function analyzeModuleSource(filePath: string, content: string): ModuleAnalysisFacts;
+export declare function getModuleAnalysisBackend(): ModuleAnalysisBackend;
+export declare function setModuleAnalysisBackend(backend: ModuleAnalysisBackend): void;
+export declare function resetModuleAnalysisBackend(): void;
+export declare function registerModuleAnalysisBackend(backend: ModuleAnalysisBackend): void;
+export declare function unregisterModuleAnalysisBackend(name: string): void;
+export declare function listModuleAnalysisBackends(): string[];
+export declare function selectModuleAnalysisBackend(name: string): ModuleAnalysisBackend;
+export declare function resolveModuleAnalysisBackendName(env?: NodeJS.ProcessEnv): string;
+export declare function configureModuleAnalysisBackend(env?: NodeJS.ProcessEnv): ModuleAnalysisBackend;
+export type { ModuleAnalysisBackend, ModuleAnalysisFacts, ModuleImportFact };

package/dist-pkg/compiler/module-analysis.js

@@ -0,0 +1,50 @@
+import {
+  createTypeScriptModuleAnalysisBackend
+} from "./analysis-backend.js";
+import { createOxcModuleAnalysisBackend } from "./backends/oxc.js";
+export const GORSEE_COMPILER_BACKEND_ENV = "GORSEE_COMPILER_BACKEND";
+const internalTypeScriptFallback = createTypeScriptModuleAnalysisBackend(), stableOxcBackend = createOxcModuleAnalysisBackend({ fallback: internalTypeScriptFallback }), moduleAnalysisBackends = new Map([
+  [stableOxcBackend.name, stableOxcBackend]
+]);
+let defaultModuleAnalysisBackend = stableOxcBackend;
+export function analyzeModuleSource(filePath, content) {
+  return defaultModuleAnalysisBackend.analyzeModuleSource(filePath, content);
+}
+export function getModuleAnalysisBackend() {
+  return defaultModuleAnalysisBackend;
+}
+export function setModuleAnalysisBackend(backend) {
+  moduleAnalysisBackends.set(backend.name, backend);
+  defaultModuleAnalysisBackend = backend;
+}
+export function resetModuleAnalysisBackend() {
+  moduleAnalysisBackends.clear();
+  moduleAnalysisBackends.set(stableOxcBackend.name, stableOxcBackend);
+  defaultModuleAnalysisBackend = stableOxcBackend;
+}
+export function registerModuleAnalysisBackend(backend) {
+  moduleAnalysisBackends.set(backend.name, backend);
+}
+export function unregisterModuleAnalysisBackend(name) {
+  if (name === stableOxcBackend.name)
+    return;
+  moduleAnalysisBackends.delete(name);
+  if (defaultModuleAnalysisBackend.name === name)
+    defaultModuleAnalysisBackend = stableOxcBackend;
+}
+export function listModuleAnalysisBackends() {
+  return [...moduleAnalysisBackends.keys()].sort();
+}
+export function selectModuleAnalysisBackend(name) {
+  const backend = moduleAnalysisBackends.get(name);
+  if (!backend)
+    throw Error(`Unknown module analysis backend "${name}". Registered backends: ${listModuleAnalysisBackends().join(", ")}`);
+  defaultModuleAnalysisBackend = backend;
+  return backend;
+}
+export function resolveModuleAnalysisBackendName(env = process.env) {
+  return env[GORSEE_COMPILER_BACKEND_ENV]?.trim() || stableOxcBackend.name;
+}
+export function configureModuleAnalysisBackend(env = process.env) {
+  return selectModuleAnalysisBackend(resolveModuleAnalysisBackendName(env));
+}

package/dist-pkg/compiler/parity.d.ts

@@ -0,0 +1,35 @@
+import type { ModuleAnalysisBackend } from "./analysis-backend.js";
+export interface ModuleAnalysisParityFixture {
+    filePath: string;
+    content: string;
+}
+export interface ModuleAnalysisParityDifference {
+    filePath: string;
+    field: "exportedNames" | "hasDefaultExport" | "title" | "meta" | "exportedLiterals" | "imports";
+    left: unknown;
+    right: unknown;
+}
+export interface ModuleAnalysisParityReport {
+    leftBackend: string;
+    rightBackend: string;
+    checkedFiles: number;
+    matches: boolean;
+    leftSurface: ModuleAnalysisParitySurface[];
+    rightSurface: ModuleAnalysisParitySurface[];
+    differences: ModuleAnalysisParityDifference[];
+}
+export interface ModuleAnalysisParitySurface {
+    filePath: string;
+    exportedNames: string[];
+    hasDefaultExport: boolean;
+    title: string;
+    meta: Record<string, unknown> | null;
+    exportedLiterals: Record<string, unknown>;
+    imports: Array<{
+        specifier: string;
+        names: string[];
+        namespace?: string;
+        hasDefaultImport: boolean;
+    }>;
+}
+export declare function compareModuleAnalysisBackends(leftBackend: ModuleAnalysisBackend, rightBackend: ModuleAnalysisBackend, fixtures: ModuleAnalysisParityFixture[]): ModuleAnalysisParityReport;

package/dist-pkg/compiler/parity.js

@@ -0,0 +1,89 @@
+export function compareModuleAnalysisBackends(leftBackend, rightBackend, fixtures) {
+  const differences = [], leftSurface = [], rightSurface = [];
+  for (const fixture of fixtures) {
+    const left = leftBackend.analyzeModuleSource(fixture.filePath, fixture.content), right = rightBackend.analyzeModuleSource(fixture.filePath, fixture.content);
+    leftSurface.push(normalizeModuleAnalysisFacts(fixture.filePath, left));
+    rightSurface.push(normalizeModuleAnalysisFacts(fixture.filePath, right));
+    collectDifferences(differences, fixture.filePath, left, right);
+  }
+  return {
+    leftBackend: leftBackend.name,
+    rightBackend: rightBackend.name,
+    checkedFiles: fixtures.length,
+    matches: differences.length === 0,
+    leftSurface,
+    rightSurface,
+    differences
+  };
+}
+function collectDifferences(differences, filePath, left, right) {
+  if (!sameStringSets(left.exportedNames, right.exportedNames))
+    differences.push({
+      filePath,
+      field: "exportedNames",
+      left: [...left.exportedNames].sort(),
+      right: [...right.exportedNames].sort()
+    });
+  if (left.hasDefaultExport !== right.hasDefaultExport)
+    differences.push({
+      filePath,
+      field: "hasDefaultExport",
+      left: left.hasDefaultExport,
+      right: right.hasDefaultExport
+    });
+  if (left.title !== right.title)
+    differences.push({
+      filePath,
+      field: "title",
+      left: left.title,
+      right: right.title
+    });
+  if (!sameJsonLike(left.meta, right.meta))
+    differences.push({
+      filePath,
+      field: "meta",
+      left: left.meta,
+      right: right.meta
+    });
+  if (!sameJsonLike(left.exportedLiterals, right.exportedLiterals))
+    differences.push({
+      filePath,
+      field: "exportedLiterals",
+      left: left.exportedLiterals,
+      right: right.exportedLiterals
+    });
+  if (!sameJsonLike(left.imports, right.imports))
+    differences.push({
+      filePath,
+      field: "imports",
+      left: left.imports,
+      right: right.imports
+    });
+}
+function sameStringSets(left, right) {
+  if (left.size !== right.size)
+    return !1;
+  for (const value of left)
+    if (!right.has(value))
+      return !1;
+  return !0;
+}
+function sameJsonLike(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function normalizeModuleAnalysisFacts(filePath, facts) {
+  return {
+    filePath,
+    exportedNames: [...facts.exportedNames].sort(),
+    hasDefaultExport: facts.hasDefaultExport,
+    title: facts.title,
+    meta: facts.meta,
+    exportedLiterals: facts.exportedLiterals,
+    imports: facts.imports.map((entry) => ({
+      specifier: entry.specifier,
+      names: [...entry.names],
+      namespace: entry.namespace,
+      hasDefaultImport: entry.hasDefaultImport
+    }))
+  };
+}

package/dist-pkg/compiler/readiness.d.ts

@@ -0,0 +1,11 @@
+import { GORSEE_COMPILER_BACKEND_ENV } from "./module-analysis.js";
+export interface CompilerBackendReadiness {
+    envVar: typeof GORSEE_COMPILER_BACKEND_ENV;
+    stableDefault: "oxc";
+    preferredCanary: "experimental-oxc";
+    selected: string;
+    resolvedFromEnv: string;
+    registered: string[];
+    experimental: string[];
+}
+export declare function getCompilerBackendReadiness(env?: NodeJS.ProcessEnv): CompilerBackendReadiness;

package/dist-pkg/compiler/readiness.js

@@ -0,0 +1,18 @@
+import {
+  GORSEE_COMPILER_BACKEND_ENV,
+  getModuleAnalysisBackend,
+  listModuleAnalysisBackends,
+  resolveModuleAnalysisBackendName
+} from "./module-analysis.js";
+export function getCompilerBackendReadiness(env = process.env) {
+  const registered = listModuleAnalysisBackends();
+  return {
+    envVar: GORSEE_COMPILER_BACKEND_ENV,
+    stableDefault: "oxc",
+    preferredCanary: "experimental-oxc",
+    selected: getModuleAnalysisBackend().name,
+    resolvedFromEnv: resolveModuleAnalysisBackendName(env),
+    registered,
+    experimental: registered.filter((name) => name.startsWith("experimental-"))
+  };
+}

package/dist-pkg/compiler/route-facts.d.ts

@@ -0,0 +1,34 @@
+import type { Route } from "../router/scanner.js";
+export declare const ROUTE_FACTS_SCHEMA_VERSION: 2;
+export interface RouteCompilerFacts {
+    schemaVersion: typeof ROUTE_FACTS_SCHEMA_VERSION;
+    path: string;
+    params: string[];
+    methods: string[];
+    hasDefaultExport: boolean;
+    hasLoader: boolean;
+    isApi: boolean;
+    hasMiddleware: boolean;
+    title: string;
+    meta: Record<string, unknown> | null;
+    declaresPrerender: boolean;
+}
+export interface RouteDocSurface {
+    path: string;
+    methods: string[];
+    hasLoader: boolean;
+    isApi: boolean;
+    hasMiddleware: boolean;
+    title: string;
+    meta: Record<string, unknown> | null;
+}
+export interface RouteFactsArtifact {
+    schemaVersion: typeof ROUTE_FACTS_SCHEMA_VERSION;
+    routes: RouteCompilerFacts[];
+}
+export declare function getRouteFactMethods(routeFacts: RouteCompilerFacts): string[];
+export declare function toRouteDocSurface(routeFacts: RouteCompilerFacts): RouteDocSurface;
+export declare function getRouteParamsRecord(routeFacts: RouteCompilerFacts): Record<string, "string">;
+export declare function inspectRouteFacts(route: Route): Promise<RouteCompilerFacts>;
+export declare function createRouteFactsArtifact(routes: Route[]): Promise<RouteFactsArtifact>;
+export declare function parseRouteFactsArtifact(raw: string): RouteFactsArtifact;

package/dist-pkg/compiler/route-facts.js

@@ -0,0 +1,75 @@
+import { readFile } from "node:fs/promises";
+import { analyzeModuleSource } from "./module-analysis.js";
+export const ROUTE_FACTS_SCHEMA_VERSION = 2;
+const HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"];
+export function getRouteFactMethods(routeFacts) {
+  const methods = [...routeFacts.methods];
+  if (methods.length === 0 && routeFacts.hasDefaultExport)
+    methods.push("GET");
+  if (methods.length === 0 && routeFacts.hasLoader)
+    methods.push("GET");
+  return methods;
+}
+export function toRouteDocSurface(routeFacts) {
+  return {
+    path: routeFacts.path,
+    methods: getRouteFactMethods(routeFacts),
+    hasLoader: routeFacts.hasLoader,
+    isApi: routeFacts.isApi,
+    hasMiddleware: routeFacts.hasMiddleware,
+    title: routeFacts.title,
+    meta: routeFacts.meta
+  };
+}
+export function getRouteParamsRecord(routeFacts) {
+  const params = {};
+  for (const param of routeFacts.params)
+    params[param] = "string";
+  return params;
+}
+export async function inspectRouteFacts(route) {
+  const content = await readFile(route.filePath, "utf-8"), facts = analyzeModuleSource(route.filePath, content), methods = HTTP_METHODS.filter((method) => facts.exportedNames.has(method)), hasLoader = facts.exportedNames.has("load") || facts.exportedNames.has("loader"), isApi = !facts.hasDefaultExport || methods.length > 0;
+  return {
+    schemaVersion: ROUTE_FACTS_SCHEMA_VERSION,
+    path: route.path,
+    params: [...route.params],
+    methods: [...methods],
+    hasDefaultExport: facts.hasDefaultExport,
+    hasLoader,
+    isApi,
+    hasMiddleware: route.middlewarePaths.length > 0,
+    title: facts.title,
+    meta: facts.meta,
+    declaresPrerender: facts.exportedLiterals.prerender === !0
+  };
+}
+export async function createRouteFactsArtifact(routes) {
+  const facts = await Promise.all(routes.map((route) => inspectRouteFacts(route)));
+  return {
+    schemaVersion: ROUTE_FACTS_SCHEMA_VERSION,
+    routes: facts
+  };
+}
+export function parseRouteFactsArtifact(raw) {
+  const artifact = JSON.parse(raw);
+  validateRouteFactsArtifact(artifact);
+  return artifact;
+}
+function validateRouteFactsArtifact(artifact) {
+  if (artifact.schemaVersion !== ROUTE_FACTS_SCHEMA_VERSION)
+    throw Error(`Unsupported route facts schema version: expected ${ROUTE_FACTS_SCHEMA_VERSION}, received ${String(artifact.schemaVersion)}`);
+  if (!Array.isArray(artifact.routes))
+    throw Error("Invalid route facts artifact: routes must be an array");
+  for (const route of artifact.routes) {
+    if (!route || typeof route !== "object")
+      throw Error("Invalid route facts artifact: route entry must be an object");
+    if (route.schemaVersion !== ROUTE_FACTS_SCHEMA_VERSION)
+      throw Error("Invalid route facts artifact: route schemaVersion drift detected");
+    if (typeof route.path !== "string" || route.path.length === 0)
+      throw Error("Invalid route facts artifact: route path must be a non-empty string");
+    if (!Array.isArray(route.params))
+      throw Error("Invalid route facts artifact: params must be an array");
+    if (!Array.isArray(route.methods))
+      throw Error("Invalid route facts artifact: methods must be an array");
+  }
+}

package/dist-pkg/content/index.d.ts

@@ -0,0 +1,27 @@
+export interface ContentEntry<TFrontmatter extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    slug: string;
+    locale: string | null;
+    body: string;
+    excerpt: string;
+    frontmatter: TFrontmatter;
+    sourcePath: string;
+}
+export interface ContentCollectionOptions<TFrontmatter extends Record<string, unknown>> {
+    dir: string;
+    includeExtensions?: string[];
+    defaultLocale?: string;
+    validate?: (frontmatter: Record<string, unknown>, entry: Omit<ContentEntry<TFrontmatter>, "frontmatter">) => TFrontmatter;
+}
+export interface ContentQueryOptions {
+    locale?: string;
+    sortBy?: "date-desc" | "date-asc" | "title-asc" | "title-desc";
+}
+export declare function parseFrontmatter(source: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+export declare function extractExcerpt(body: string, maxLength?: number): string;
+export declare function loadContentCollection<TFrontmatter extends Record<string, unknown> = Record<string, unknown>>(options: ContentCollectionOptions<TFrontmatter>): Promise<Array<ContentEntry<TFrontmatter>>>;
+export declare function queryContent<TFrontmatter extends Record<string, unknown>>(entries: Array<ContentEntry<TFrontmatter>>, options?: ContentQueryOptions): Array<ContentEntry<TFrontmatter>>;
+export declare function getContentEntryBySlug<TFrontmatter extends Record<string, unknown>>(entries: Array<ContentEntry<TFrontmatter>>, slug: string, locale?: string): ContentEntry<TFrontmatter> | null;