@typed/app 1.0.0-beta.1

package/src/internal/emitRouterSource.ts

@@ -0,0 +1,191 @@
+import { basename, dirname, join, relative } from "node:path";
+import {
+  buildRouterDescriptorTree,
+  renderRouterDescriptorTree,
+  type RouteMatchDescriptor,
+} from "./routerDescriptorTree.js";
+import type {
+  CatchFormByPath,
+  CatchExportByPath,
+  DepsFormByPath,
+  GuardExportByPath,
+  RouteDescriptor,
+} from "./buildRouteDescriptors.js";
+import { siblingCompanionPath, type ConcernKind } from "./buildRouteDescriptors.js";
+import { catchExprFor, depsExprFor, handlerExprFor } from "./emitRouterHelpers.js";
+import { makeUniqueVarNames, pathToIdentifier, routeModuleIdentifier } from "./routeIdentifiers.js";
+import { stripScriptExtension, toPosixPath } from "./path.js";
+
+/** Path relative to baseDir → import specifier relative to importerDir (script ext → .js for ESM). */
+function toImportSpecifier(
+  importerDir: string,
+  targetDir: string,
+  relativeFilePath: string,
+): string {
+  const absPath = join(targetDir, relativeFilePath);
+  const rel = toPosixPath(relative(importerDir, absPath));
+  const specifier = rel.startsWith(".") ? rel : `./${rel}`;
+  return stripScriptExtension(specifier) + ".js";
+}
+
+/** Canonical root directory: Node's dirname returns "." for root-level files; we use "" consistently. */
+function normalizeDir(dir: string): string {
+  return dir === "." ? "" : dir;
+}
+
+/** True iff the companion path is directory-level (e.g. api/_layout.ts), not sibling (e.g. route.layout.ts). */
+function isDirectoryCompanion(p: string): boolean {
+  return basename(p).startsWith("_");
+}
+
+/** Directory path -> companion paths for that directory (only _layout, _dependencies, _catch; guard is per-route). */
+function directoryCompanionPaths(
+  descriptors: readonly RouteDescriptor[],
+): Map<string, { layout?: string; dependencies?: string; catch?: string }> {
+  const map = new Map<string, { layout?: string; dependencies?: string; catch?: string }>();
+  for (const d of descriptors) {
+    for (const kind of ["layout", "dependencies", "catch"] as const) {
+      for (const p of d.composedConcerns[kind]) {
+        if (!isDirectoryCompanion(p)) continue;
+        const dir = normalizeDir(dirname(p));
+        let entry = map.get(dir);
+        if (!entry) {
+          entry = {};
+          map.set(dir, entry);
+        }
+        if (!entry[kind]) entry[kind] = p;
+      }
+    }
+  }
+  return map;
+}
+
+/** Collect unique paths in leaf→ancestor order (closest to route first; first occurrence wins). */
+function collectOrderedCompanionPaths(
+  descriptors: readonly RouteDescriptor[],
+  kind: ConcernKind,
+): readonly string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const d of descriptors) {
+    const paths = d.composedConcerns[kind];
+    for (const p of paths) {
+      if (!seen.has(p)) {
+        seen.add(p);
+        out.push(p);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Emit Router.merge(...) of directory matchers. Each route compiles to .match(route, { handler, ...opts })
+ * with opts only from in-file or sibling. Directory companions (_layout, _dependencies, _catch) apply to
+ * all routes in that directory and are added once per directory via .layout(), .provide(), .catchCause().
+ */
+export function emitRouterMatchSource(
+  descriptors: readonly RouteDescriptor[],
+  targetDirectory: string,
+  importer: string,
+  guardExportByPath: GuardExportByPath,
+  catchExportByPath: CatchExportByPath,
+  catchFormByPath: CatchFormByPath,
+  depsFormByPath: DepsFormByPath,
+): string {
+  const importerDir = dirname(toPosixPath(importer));
+  const needsFnErrorImports = Object.values(catchFormByPath).some((f) => f.form === "fn-error");
+  const needsLayerImport = Object.values(depsFormByPath).includes("servicemap");
+  const depPaths = collectOrderedCompanionPaths(descriptors, "dependencies");
+  const layoutPaths = collectOrderedCompanionPaths(descriptors, "layout");
+  const guardPaths = collectOrderedCompanionPaths(descriptors, "guard");
+  const catchPaths = collectOrderedCompanionPaths(descriptors, "catch");
+
+  const nameEntries: { path: string; proposedName: string }[] = [
+    ...descriptors.map((d) => ({
+      path: d.filePath,
+      proposedName: routeModuleIdentifier(d.filePath),
+    })),
+    ...depPaths.map((p) => ({ path: p, proposedName: pathToIdentifier(p) })),
+    ...layoutPaths.map((p) => ({ path: p, proposedName: pathToIdentifier(p) })),
+    ...guardPaths.map((p) => ({ path: p, proposedName: pathToIdentifier(p) })),
+    ...catchPaths.map((p) => ({ path: p, proposedName: pathToIdentifier(p) })),
+  ];
+  const varNameByPath = makeUniqueVarNames(nameEntries);
+
+  const importLines: string[] = [
+    `import * as Router from "@typed/router";`,
+    `import * as Fx from "@typed/fx/Fx";`,
+    `import { constant } from "effect/Function";`,
+    ...(needsFnErrorImports
+      ? [
+          `import * as Effect from "effect/Effect";`,
+          `import * as Cause from "effect/Cause";`,
+          `import * as Result from "effect/Result";`,
+        ]
+      : []),
+    ...(needsLayerImport ? [`import * as Layer from "effect/Layer";`] : []),
+  ];
+
+  for (const d of descriptors) {
+    const spec = toImportSpecifier(importerDir, targetDirectory, d.filePath);
+    const varName = varNameByPath.get(d.filePath)!;
+    importLines.push(`import * as ${varName} from ${JSON.stringify(spec)};`);
+  }
+  for (const p of depPaths) {
+    importLines.push(
+      `import * as ${varNameByPath.get(p)} from ${JSON.stringify(toImportSpecifier(importerDir, targetDirectory, p))};`,
+    );
+  }
+  for (const p of layoutPaths) {
+    importLines.push(
+      `import * as ${varNameByPath.get(p)} from ${JSON.stringify(toImportSpecifier(importerDir, targetDirectory, p))};`,
+    );
+  }
+  for (const p of guardPaths) {
+    importLines.push(
+      `import * as ${varNameByPath.get(p)} from ${JSON.stringify(toImportSpecifier(importerDir, targetDirectory, p))};`,
+    );
+  }
+  for (const p of catchPaths) {
+    importLines.push(
+      `import * as ${varNameByPath.get(p)} from ${JSON.stringify(toImportSpecifier(importerDir, targetDirectory, p))};`,
+    );
+  }
+
+  const dirToCompanions = directoryCompanionPaths(descriptors);
+  const descriptorTree = buildRouterDescriptorTree({
+    descriptors,
+    dirToCompanions,
+    guardExportByPath,
+    catchExportByPath,
+    catchFormByPath,
+    normalizeDir,
+    isDirectoryCompanion,
+    siblingCompanionPath,
+  });
+  const handlerExprForMatch = (match: RouteMatchDescriptor, varName: string) =>
+    handlerExprFor(
+      match.runtimeKind,
+      match.entrypointIsFunction,
+      match.entrypointExpectsRefSubject,
+      varName,
+      match.entrypointExport,
+    );
+  const rootSource = renderRouterDescriptorTree(descriptorTree, {
+    varNameByPath,
+    guardExportByPath,
+    catchExportByPath,
+    catchFormByPath,
+    depsFormByPath,
+    handlerExprFor: handlerExprForMatch,
+    catchExprFor,
+    depsExprFor,
+  });
+
+  return `${importLines.join("\n")}
+
+const router = ${rootSource};
+export default router;
+`;
+}

package/src/internal/extractHttpApiLiterals.ts

@@ -0,0 +1,67 @@
+/**
+ * Extract path and method from endpoint TypeInfo snapshot.
+ * Uses TypeInfoApi export types instead of parsing source with TypeScript.
+ * Handles literal, object, and reference (e.g. Route<P,S>) shapes; unknown kinds return null.
+ */
+import type {
+  LiteralTypeNode,
+  ObjectTypeNode,
+  ReferenceTypeNode,
+  TypeInfoFileSnapshot,
+  TypeNode,
+} from "@typed/virtual-modules";
+
+export interface ExtractedEndpointLiterals {
+  readonly path: string;
+  readonly method: string;
+  readonly name: string;
+}
+
+function getLiteralText(node: TypeNode | undefined): string | null {
+  if (!node || node.kind !== "literal") return null;
+  return (node as LiteralTypeNode).text || null;
+}
+
+function getPathFromRouteType(type: TypeNode): string | null {
+  if (type.kind === "literal") {
+    const raw = (type as LiteralTypeNode).text;
+    return raw ? (raw.startsWith("/") ? raw : `/${raw}`) : null;
+  }
+  if (type.kind === "object") {
+    const pathProp = (type as ObjectTypeNode).properties.find((p) => p.name === "path");
+    if (!pathProp) return null;
+    const raw = getLiteralText(pathProp.type);
+    return raw ? (raw.startsWith("/") ? raw : `/${raw}`) : null;
+  }
+  if (type.kind === "reference") {
+    const typeArgs = (type as ReferenceTypeNode).typeArguments;
+    if (typeArgs?.length) return getPathFromRouteType(typeArgs[0]);
+  }
+  return null;
+}
+
+/**
+ * Extracts route path and method from TypeInfo snapshot exports.
+ * Reads from route and method exports; path from route type (literal or object.path).
+ */
+export function extractEndpointLiterals(
+  snapshot: TypeInfoFileSnapshot,
+  stem: string,
+): ExtractedEndpointLiterals {
+  let path = `/${stem}`;
+  let method = "GET";
+
+  const routeExport = snapshot.exports.find((e) => e.name === "route");
+  if (routeExport) {
+    const p = getPathFromRouteType(routeExport.type);
+    if (p) path = p;
+  }
+
+  const methodExport = snapshot.exports.find((e) => e.name === "method");
+  if (methodExport) {
+    const m = getLiteralText(methodExport.type);
+    if (m) method = m.toUpperCase();
+  }
+
+  return { path, method, name: stem };
+}

package/src/internal/httpapiDescriptorTree.ts

@@ -0,0 +1,283 @@
+/**
+ * Filesystem tree AST for HttpApi virtual module discovery.
+ * Converts role-classified artifacts into a deterministic tree (ApiRoot, Group, PathlessDirectory, Endpoint, Convention metadata).
+ * Parenthesized pathless directories do not create a named group but preserve composition order.
+ */
+
+import type {
+  HttpApiDirectoryCompanionKind,
+  HttpApiEndpointCompanionKind,
+  HttpApiFileRole,
+} from "./httpapiFileRoles.js";
+import {
+  compareHttpApiPathOrder,
+  sortHttpApiPaths,
+} from "./httpapiFileRoles.js";
+
+/** Path segment is pathless when it matches (name) and does not create an HttpApiGroup. */
+const PATHLESS_DIRECTORY_PATTERN = /^\([^)]*\)$/;
+
+export function isPathlessDirectorySegment(segment: string): boolean {
+  return PATHLESS_DIRECTORY_PATTERN.test(segment);
+}
+
+/** Reference to a directory-level convention file (e.g. _dependencies.ts). */
+export type DirectoryConventionRef = {
+  readonly path: string;
+  readonly kind: HttpApiDirectoryCompanionKind;
+};
+
+/** Reference to API root or group override convention. */
+export type RootOrGroupConventionRef = {
+  readonly path: string;
+  readonly kind: "api_root" | "group_override";
+};
+
+/** Reference to an endpoint companion file (e.g. list.openapi.ts). */
+export type EndpointCompanionRef = {
+  readonly path: string;
+  readonly kind: HttpApiEndpointCompanionKind;
+};
+
+/** Leaf node: endpoint primary with optional companion refs. */
+export type HttpApiEndpointNode = {
+  readonly type: "endpoint";
+  readonly path: string;
+  /** Filename stem without extension (e.g. "list"). */
+  readonly stem: string;
+  readonly companions: readonly EndpointCompanionRef[];
+};
+
+/** Directory that does not create a named group (e.g. (internal)). */
+export type HttpApiPathlessDirectoryNode = {
+  readonly type: "pathless_directory";
+  /** Full relative dir path (e.g. "users/(internal)"). */
+  readonly dirPath: string;
+  readonly conventions: readonly (DirectoryConventionRef | RootOrGroupConventionRef)[];
+  readonly children: readonly HttpApiTreeNode[];
+};
+
+/** Named group directory (creates HttpApiGroup). */
+export type HttpApiGroupNode = {
+  readonly type: "group";
+  /** Group name (default from directory segment, override from _group.ts). */
+  readonly groupName: string;
+  /** Full relative dir path (e.g. "users"). */
+  readonly dirPath: string;
+  readonly children: readonly HttpApiTreeNode[];
+  readonly conventions: readonly (DirectoryConventionRef | RootOrGroupConventionRef)[];
+};
+
+export type HttpApiTreeNode =
+  | HttpApiEndpointNode
+  | HttpApiGroupNode
+  | HttpApiPathlessDirectoryNode;
+
+/** Root of the descriptor tree. */
+export type HttpApiDescriptorTree = {
+  readonly type: "api_root";
+  readonly dirPath: "";
+  readonly children: readonly HttpApiTreeNode[];
+  readonly conventions: readonly (DirectoryConventionRef | RootOrGroupConventionRef)[];
+  /** Diagnostics-ready: unsupported roles collected during parse. */
+  readonly diagnostics: readonly HttpApiTreeDiagnostic[];
+};
+
+export type HttpApiTreeDiagnostic = {
+  readonly code: string;
+  readonly message: string;
+  readonly path: string;
+};
+
+export type BuildHttpApiDescriptorTreeInput = {
+  /** Classified file roles (supported and unsupported_reserved). */
+  readonly roles: readonly HttpApiFileRole[];
+  /** Optional: only include paths under this base (relative); not used for filtering if empty. */
+  readonly baseDir?: string;
+};
+
+/**
+ * Builds a deterministic tree AST from classified file roles.
+ * Pathless directory segments (e.g. "(internal)") are represented as PathlessDirectoryNode and do not create a group name.
+ */
+export function buildHttpApiDescriptorTree(
+  input: BuildHttpApiDescriptorTreeInput,
+): HttpApiDescriptorTree {
+  const { roles } = input;
+  const diagnostics: HttpApiTreeDiagnostic[] = [];
+  const supported: HttpApiFileRole[] = [];
+  for (const r of roles) {
+    if (r.role === "unsupported_reserved") {
+      diagnostics.push({
+        code: r.diagnosticCode,
+        message: r.diagnosticMessage,
+        path: r.path,
+      });
+    } else {
+      supported.push(r);
+    }
+  }
+
+  const apiRootConventions: (DirectoryConventionRef | RootOrGroupConventionRef)[] = [];
+  const directoryConventionsByDir = new Map<string, (DirectoryConventionRef | RootOrGroupConventionRef)[]>();
+  const endpointCompanionsByKey = new Map<string, EndpointCompanionRef[]>();
+
+  for (const r of supported) {
+    if (r.role === "api_root") {
+      apiRootConventions.push({ path: r.path, kind: "api_root" });
+      continue;
+    }
+    if (r.role === "group_override") {
+      const dir = dirname(r.path);
+      directoryConventionsByDir.set(dir, [
+        ...(directoryConventionsByDir.get(dir) ?? []),
+        { path: r.path, kind: "group_override" },
+      ]);
+      continue;
+    }
+    if (r.role === "directory_companion") {
+      const dir = dirname(r.path);
+      const list = directoryConventionsByDir.get(dir) ?? [];
+      list.push({ path: r.path, kind: r.kind });
+      directoryConventionsByDir.set(dir, list);
+      continue;
+    }
+    if (r.role === "endpoint_primary") {
+      continue;
+    }
+    if (r.role === "endpoint_companion") {
+      const dir = dirname(r.path);
+      const key = dir ? `${dir}/${r.endpointStem}` : r.endpointStem;
+      const list = endpointCompanionsByKey.get(key) ?? [];
+      list.push({ path: r.path, kind: r.kind });
+      endpointCompanionsByKey.set(key, list);
+    }
+  }
+
+  const allDirs = new Set<string>();
+  function addDirAndAncestors(d: string): void {
+    allDirs.add(d);
+    const idx = d.lastIndexOf("/");
+    if (idx > 0) addDirAndAncestors(d.slice(0, idx));
+  }
+  for (const r of supported) {
+    const p = "path" in r ? r.path : "";
+    addDirAndAncestors(dirname(p));
+  }
+  for (const [dir] of directoryConventionsByDir) {
+    addDirAndAncestors(dir);
+  }
+  const sortedDirs = sortHttpApiPaths([...allDirs]);
+
+  const dirSegments = (dirPath: string): string[] =>
+    dirPath ? dirPath.split("/").filter(Boolean) : [];
+
+  const childrenByParentDir = new Map<string, string[]>();
+  for (const d of sortedDirs) {
+    const segments = dirSegments(d);
+    if (segments.length === 0) continue;
+    const parent = segments.length === 1 ? "" : segments.slice(0, -1).join("/");
+    const list = childrenByParentDir.get(parent) ?? [];
+    if (!list.includes(d)) list.push(d);
+    childrenByParentDir.set(parent, list);
+  }
+
+  function buildNode(dirPath: string): HttpApiTreeNode[] {
+    const directFiles = supported
+      .filter((r) => {
+        if (r.role !== "endpoint_primary") return false;
+        const p = r.path;
+        const d = dirname(p);
+        return d === dirPath;
+      })
+      .map((r) => r as { role: "endpoint_primary"; path: string })
+      .sort((a, b) => compareHttpApiPathOrder(a.path, b.path));
+
+    const childDirs = (childrenByParentDir.get(dirPath) ?? []).slice().sort(compareHttpApiPathOrder);
+    const nodes: HttpApiTreeNode[] = [];
+
+    for (const f of directFiles) {
+      const stem = stemFromPath(f.path);
+      const companionKey = dirPath ? `${dirPath}/${stem}` : stem;
+      const companions = endpointCompanionsByKey.get(companionKey) ?? [];
+      nodes.push({
+        type: "endpoint",
+        path: f.path,
+        stem,
+        companions: [...companions].sort((a, b) => compareHttpApiPathOrder(a.path, b.path)),
+      });
+    }
+
+    for (const childDir of childDirs) {
+      const segments = dirSegments(childDir);
+      const segmentName = segments[segments.length - 1] ?? "";
+      if (isPathlessDirectorySegment(segmentName)) {
+        const childNodes = buildNode(childDir);
+        const conventions = directoryConventionsByDir.get(childDir) ?? [];
+        nodes.push({
+          type: "pathless_directory",
+          dirPath: childDir,
+          conventions: [...conventions].sort((a, b) => compareHttpApiPathOrder(a.path, b.path)),
+          children: childNodes.length === 0 ? [] : childNodes.slice().sort(compareTreeNodes),
+        });
+      } else {
+        const groupName = segmentName;
+        const childNodes = buildNode(childDir);
+        const conventions = directoryConventionsByDir.get(childDir) ?? [];
+        nodes.push({
+          type: "group",
+          groupName,
+          dirPath: childDir,
+          children: childNodes.length === 0 ? [] : childNodes.slice().sort(compareTreeNodes),
+          conventions: [...conventions].sort((a, b) => compareHttpApiPathOrder(a.path, b.path)),
+        });
+      }
+    }
+
+    return nodes.slice().sort(compareTreeNodes);
+  }
+
+  const rootChildren = buildNode("");
+  const rootConventions = [...apiRootConventions];
+  const rootDirConventions = directoryConventionsByDir.get("") ?? [];
+  for (const c of rootDirConventions) {
+    rootConventions.push(c);
+  }
+  rootConventions.sort((a, b) => compareHttpApiPathOrder(a.path, b.path));
+
+  return {
+    type: "api_root",
+    dirPath: "",
+    children: rootChildren,
+    conventions: rootConventions,
+    diagnostics,
+  };
+}
+
+function dirname(p: string): string {
+  const i = p.lastIndexOf("/");
+  return i < 0 ? "" : p.slice(0, i);
+}
+
+function stemFromPath(path: string): string {
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  const extIdx = base.lastIndexOf(".");
+  return extIdx <= 0 ? base : base.slice(0, extIdx);
+}
+
+function nodeSortKey(n: HttpApiTreeNode): string {
+  switch (n.type) {
+    case "endpoint":
+      return n.path;
+    case "group":
+    case "pathless_directory":
+      return n.dirPath;
+    default:
+      return "";
+  }
+}
+
+function compareTreeNodes(a: HttpApiTreeNode, b: HttpApiTreeNode): number {
+  return compareHttpApiPathOrder(nodeSortKey(a), nodeSortKey(b));
+}
+

package/src/internal/httpapiEndpointContract.ts

@@ -0,0 +1,110 @@
+/**
+ * Endpoint contract validation for HttpApi virtual module.
+ * Validates required fields (route, method, handler). Optional: headers, body, error, success.
+ * Route covers path + query; headers/body mirror decoders from HttpServerRequest;
+ * error/success encode response payloads with annotated status codes.
+ * Handler returns require structural type checking (assignable to success/error schemas)
+ * and coercion into HttpServerResponse via Effect's HttpApi layer.
+ *
+ * @see .docs/specs/httpapi-virtual-module-plugin/spec.md (Endpoint contract, Endpoint Contract Validator)
+ */
+
+import type { ValidationResult } from "./validation.js";
+import { validateNonEmptyString } from "./validation.js";
+
+/** Supported HTTP method literals for endpoint contract */
+const HTTP_METHODS = new Set<string>([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+]);
+
+/** Minimal endpoint contract shape (runtime check) */
+export interface EndpointContractInput {
+  readonly route?: unknown;
+  readonly method?: unknown;
+  readonly handler?: unknown;
+  readonly headers?: unknown;
+  readonly body?: unknown;
+  readonly error?: unknown;
+  readonly success?: unknown;
+}
+
+/** Validated endpoint contract */
+export interface ValidatedEndpointContract {
+  readonly route: unknown;
+  readonly method: string;
+  readonly handler: unknown;
+}
+
+/**
+ * Checks that value is a non-null object (route/schema-like values are objects).
+ */
+function isObject(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * Validates endpoint contract: required route, method, handler; optional headers, body, error, success.
+ */
+export function validateEndpointContract(
+  input: unknown,
+): ValidationResult<ValidatedEndpointContract> {
+  if (!isObject(input)) {
+    return { ok: false, reason: "Endpoint contract must be an object" };
+  }
+
+  const contract = input as Record<string, unknown>;
+
+  if (contract.route === undefined) {
+    return { ok: false, reason: "Endpoint contract missing required field: route" };
+  }
+  if (!isObject(contract.route)) {
+    return { ok: false, reason: "Endpoint contract route must be an object (path + pathSchema + querySchema)" };
+  }
+
+  const route = contract.route as Record<string, unknown>;
+  if (route.pathSchema === undefined) {
+    return { ok: false, reason: "Endpoint contract route must include pathSchema" };
+  }
+  if (route.querySchema === undefined) {
+    return { ok: false, reason: "Endpoint contract route must include querySchema" };
+  }
+
+  const methodResult = validateNonEmptyString(contract.method, "method");
+  if (!methodResult.ok) {
+    return {
+      ok: false,
+      reason: `Endpoint contract method: ${methodResult.reason}`,
+    };
+  }
+  if (!HTTP_METHODS.has(methodResult.value)) {
+    return {
+      ok: false,
+      reason: `Endpoint contract method must be one of: ${[...HTTP_METHODS].join(", ")}`,
+    };
+  }
+
+  if (contract.handler === undefined) {
+    return { ok: false, reason: "Endpoint contract missing required field: handler" };
+  }
+  if (typeof contract.handler !== "function") {
+    return {
+      ok: false,
+      reason: "Endpoint contract handler must be a function",
+    };
+  }
+
+  return {
+    ok: true,
+    value: {
+      route: contract.route,
+      method: methodResult.value,
+      handler: contract.handler,
+    },
+  };
+}