@typed/app 1.0.0-beta.1

package/src/internal/httpapiFileRoles.ts

@@ -0,0 +1,204 @@
+/**
+ * File-role classification for HttpApi virtual module discovery.
+ * Implements the supported file-role matrix: API root, group, endpoint primary, endpoint companions, directory companions.
+ * Diagnostics-ready metadata for unsupported reserved names.
+ */
+
+import { toPosixPath } from "./path.js";
+
+/** Script extensions that count as API source candidates (aligned with router plugin). */
+export const HTTPAPI_SCRIPT_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mts",
+  ".cts",
+  ".mjs",
+  ".cjs",
+] as const;
+
+export const HTTPAPI_SCRIPT_EXTENSION_SET = new Set<string>(
+  HTTPAPI_SCRIPT_EXTENSIONS.map((e) => e.toLowerCase()),
+);
+
+/** Directory companion filenames (exact match). */
+export const HTTPAPI_DIRECTORY_COMPANION_FILES = [
+  "_dependencies.ts",
+  "_middlewares.ts",
+  "_prefix.ts",
+  "_openapi.ts",
+] as const;
+
+/** Endpoint companion suffixes (stem ends with these before extension). */
+export const HTTPAPI_ENDPOINT_COMPANION_SUFFIXES = [
+  ".name",
+  ".dependencies",
+  ".middlewares",
+  ".prefix",
+  ".openapi",
+] as const;
+
+export type HttpApiDirectoryCompanionKind =
+  (typeof HTTPAPI_DIRECTORY_COMPANION_FILES)[number];
+export type HttpApiEndpointCompanionKind =
+  (typeof HTTPAPI_ENDPOINT_COMPANION_SUFFIXES)[number];
+
+/** Role of a discovered file relative to the API root. */
+export type HttpApiFileRole =
+  | { readonly role: "api_root"; readonly path: string }
+  | { readonly role: "group_override"; readonly path: string }
+  | { readonly role: "endpoint_primary"; readonly path: string }
+  | {
+      readonly role: "endpoint_companion";
+      readonly path: string;
+      readonly kind: HttpApiEndpointCompanionKind;
+      readonly endpointStem: string;
+    }
+  | {
+      readonly role: "directory_companion";
+      readonly path: string;
+      readonly kind: HttpApiDirectoryCompanionKind;
+    }
+  | {
+      readonly role: "unsupported_reserved";
+      readonly path: string;
+      readonly diagnosticCode: string;
+      readonly diagnosticMessage: string;
+    };
+
+/** Diagnostic-ready metadata for classification issues (e.g. unsupported companion name). */
+export type HttpApiFileRoleDiagnostic = {
+  readonly code: string;
+  readonly message: string;
+  readonly path: string;
+};
+
+const DIRECTORY_COMPANION_SET = new Set<string>(
+  HTTPAPI_DIRECTORY_COMPANION_FILES.map((f) => f.toLowerCase()),
+);
+
+/** Normalized path (posix) relative to API base; used for stable ordering. */
+export function normalizeHttpApiRelativePath(relativePath: string): string {
+  const posix = toPosixPath(relativePath);
+  return posix.replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+
+/**
+ * Returns true if the file has a supported script extension for API discovery.
+ */
+export function isHttpApiScriptExtension(ext: string): boolean {
+  return HTTPAPI_SCRIPT_EXTENSION_SET.has(ext.toLowerCase());
+}
+
+/**
+ * Classifies a single file path (relative to API root, posix) into an HttpApi file role.
+ * Does not read the filesystem; only interprets path and filename.
+ * Returns diagnostic-ready metadata for unsupported reserved names.
+ */
+export function classifyHttpApiFileRole(relativePath: string): HttpApiFileRole {
+  const path = normalizeHttpApiRelativePath(relativePath);
+  const lastSlash = path.lastIndexOf("/");
+  const dir = lastSlash < 0 ? "" : path.slice(0, lastSlash);
+  const fileName = lastSlash < 0 ? path : path.slice(lastSlash + 1);
+  const lower = fileName.toLowerCase();
+
+  if (lower.endsWith(".d.ts")) {
+    return {
+      role: "unsupported_reserved",
+      path,
+      diagnosticCode: "HTTPAPI-ROLE-001",
+      diagnosticMessage: `declaration files are not API sources: ${fileName}`,
+    };
+  }
+
+  const extIdx = fileName.lastIndexOf(".");
+  if (extIdx <= 0) {
+    return {
+      role: "unsupported_reserved",
+      path,
+      diagnosticCode: "HTTPAPI-ROLE-002",
+      diagnosticMessage: `filename must have a script extension: ${fileName}`,
+    };
+  }
+  const ext = fileName.slice(extIdx);
+  if (!isHttpApiScriptExtension(ext)) {
+    return {
+      role: "unsupported_reserved",
+      path,
+      diagnosticCode: "HTTPAPI-ROLE-003",
+      diagnosticMessage: `unsupported extension for API source: ${fileName}`,
+    };
+  }
+
+  const stem = fileName.slice(0, extIdx);
+
+  if (stem === "_api" && dir === "") {
+    return { role: "api_root", path };
+  }
+  if (stem === "_group") {
+    return { role: "group_override", path };
+  }
+  if (DIRECTORY_COMPANION_SET.has(fileName)) {
+    const kind = HTTPAPI_DIRECTORY_COMPANION_FILES.find(
+      (k) => k.toLowerCase() === lower,
+    )!;
+    return { role: "directory_companion", path, kind };
+  }
+  if (stem === "_api" || stem === "_group") {
+    return {
+      role: "unsupported_reserved",
+      path,
+      diagnosticCode: "HTTPAPI-ROLE-004",
+      diagnosticMessage: `convention file "${fileName}" must be at API root (_api.ts) or directory root (_group.ts)`,
+    };
+  }
+
+  for (const suffix of HTTPAPI_ENDPOINT_COMPANION_SUFFIXES) {
+    if (stem.endsWith(suffix)) {
+      const endpointStem = stem.slice(0, -suffix.length);
+      if (endpointStem === "") {
+        return {
+          role: "unsupported_reserved",
+          path,
+          diagnosticCode: "HTTPAPI-ROLE-005",
+          diagnosticMessage: `endpoint companion must have a base name: ${fileName}`,
+        };
+      }
+      return {
+        role: "endpoint_companion",
+        path,
+        kind: suffix as HttpApiEndpointCompanionKind,
+        endpointStem,
+      };
+    }
+  }
+
+  if (stem.startsWith("_")) {
+    return {
+      role: "unsupported_reserved",
+      path,
+      diagnosticCode: "HTTPAPI-ROLE-006",
+      diagnosticMessage: `reserved underscore-prefixed filename not in supported matrix: ${fileName}`,
+    };
+  }
+
+  return { role: "endpoint_primary", path };
+}
+
+/**
+ * Stable sort key for discovered files: normalized relative path (posix).
+ * Use with Array.sort(compareHttpApiPathOrder) for deterministic ordering.
+ */
+export function compareHttpApiPathOrder(a: string, b: string): number {
+  const na = normalizeHttpApiRelativePath(a);
+  const nb = normalizeHttpApiRelativePath(b);
+  return na.localeCompare(nb, "en");
+}
+
+/**
+ * Sorts an array of relative paths in deterministic API discovery order.
+ */
+export function sortHttpApiPaths(paths: readonly string[]): string[] {
+  return [...paths].sort(compareHttpApiPathOrder);
+}

package/src/internal/httpapiId.ts

@@ -0,0 +1,78 @@
+/**
+ * Parse and resolve `api:` virtual module IDs (router-plugin semantics).
+ * Used by HttpApi virtual module plugin for target-directory resolution.
+ */
+
+import { dirname } from "node:path";
+import { pathIsUnderBase, resolvePathUnderBase, toPosixPath } from "./path.js";
+import { validateNonEmptyString, validatePathSegment } from "./validation.js";
+
+export const HTTPAPI_VIRTUAL_MODULE_PREFIX = "api:";
+
+export type ParseHttpApiVirtualModuleIdResult =
+  | { readonly ok: true; readonly relativeDirectory: string }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * Parses an `api:./<directory>` (or `api:<directory>`) ID.
+ * Normalizes bare directory to `./<directory>`.
+ */
+export function parseHttpApiVirtualModuleId(
+  id: string,
+  prefix: string = HTTPAPI_VIRTUAL_MODULE_PREFIX,
+): ParseHttpApiVirtualModuleIdResult {
+  const idResult = validateNonEmptyString(id, "id");
+  if (!idResult.ok) return { ok: false, reason: idResult.reason };
+  const prefixResult = validateNonEmptyString(prefix, "prefix");
+  if (!prefixResult.ok) return { ok: false, reason: prefixResult.reason };
+  if (!id.startsWith(prefix)) {
+    return { ok: false, reason: `id must start with "${prefix}"` };
+  }
+
+  let relativeDirectory = id.slice(prefix.length);
+  if (
+    relativeDirectory.length > 0 &&
+    relativeDirectory !== "." &&
+    relativeDirectory !== ".." &&
+    !relativeDirectory.startsWith("./") &&
+    !relativeDirectory.startsWith("../") &&
+    !relativeDirectory.startsWith("/")
+  ) {
+    relativeDirectory = `./${relativeDirectory}`;
+  }
+  const relativeResult = validatePathSegment(relativeDirectory, "relativeDirectory");
+  if (!relativeResult.ok) return { ok: false, reason: relativeResult.reason };
+
+  return { ok: true, relativeDirectory: relativeResult.value };
+}
+
+export type ResolveHttpApiTargetDirectoryResult =
+  | { readonly ok: true; readonly targetDirectory: string }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * Resolves the target directory for an `api:` ID relative to the importer.
+ * Rejects paths that escape the importer base directory.
+ */
+export function resolveHttpApiTargetDirectory(
+  id: string,
+  importer: string,
+  prefix: string = HTTPAPI_VIRTUAL_MODULE_PREFIX,
+): ResolveHttpApiTargetDirectoryResult {
+  const parsed = parseHttpApiVirtualModuleId(id, prefix);
+  if (!parsed.ok) return parsed;
+
+  const importerResult = validatePathSegment(importer, "importer");
+  if (!importerResult.ok) return { ok: false, reason: importerResult.reason };
+
+  const importerDir = dirname(toPosixPath(importerResult.value));
+  const resolved = resolvePathUnderBase(importerDir, parsed.relativeDirectory);
+  if (!resolved.ok) {
+    return { ok: false, reason: "resolved target directory escapes importer base directory" };
+  }
+  if (!pathIsUnderBase(importerDir, resolved.path)) {
+    return { ok: false, reason: "resolved target directory is outside importer base directory" };
+  }
+
+  return { ok: true, targetDirectory: toPosixPath(resolved.path) };
+}

package/src/internal/httpapiOpenApiConfig.ts

@@ -0,0 +1,228 @@
+/**
+ * OpenAPI config mapper for HttpApi virtual module plugin.
+ * Maps convention/option layers to Effect-backed surfaces:
+ * - OpenApi.annotations keys
+ * - OpenApi.fromApi additionalProperties (API scope only)
+ * - Exposure: jsonPath, swaggerPath, scalar (json/swagger/scalar modes)
+ * Scope validation and route-conflict diagnostics are applied.
+ */
+
+/** Supported OpenApi.annotation keys (Effect-backed). */
+export const OPENAPI_ANNOTATION_KEYS = [
+  "identifier",
+  "title",
+  "version",
+  "description",
+  "license",
+  "summary",
+  "deprecated",
+  "externalDocs",
+  "servers",
+  "format",
+  "override",
+  "exclude",
+  "transform",
+] as const;
+
+export type OpenApiAnnotationKey = (typeof OPENAPI_ANNOTATION_KEYS)[number];
+
+export const OPENAPI_ANNOTATION_KEY_SET = new Set<string>(OPENAPI_ANNOTATION_KEYS);
+
+/** Scope at which OpenAPI config is applied. */
+export type OpenApiConfigScope = "api" | "group" | "endpoint";
+
+/** Annotation-only config (allowed at api, group, endpoint). */
+export interface OpenApiAnnotationsConfig {
+  readonly [key: string]: unknown;
+}
+
+/** Spec generation options (API scope only). */
+export interface OpenApiGenerationConfig {
+  readonly additionalProperties?: boolean | Record<string, unknown>;
+}
+
+/** Scalar exposure config. */
+export interface OpenApiScalarExposureConfig {
+  readonly path?: `/${string}`;
+  readonly source?: "inline" | "cdn";
+  readonly version?: string;
+  readonly config?: Record<string, unknown>;
+}
+
+/** Exposure routes (API scope only). */
+export interface OpenApiExposureConfig {
+  readonly jsonPath?: `/${string}` | false;
+  readonly swaggerPath?: `/${string}` | false;
+  readonly scalar?: OpenApiScalarExposureConfig | false;
+}
+
+/** Normalized OpenAPI config after scope validation. */
+export interface NormalizedOpenApiConfig {
+  readonly annotations: OpenApiAnnotationsConfig;
+  readonly generation: OpenApiGenerationConfig;
+  readonly exposure: OpenApiExposureConfig;
+}
+
+/** Diagnostic for OpenAPI config validation. */
+export interface OpenApiConfigDiagnostic {
+  readonly code: string;
+  readonly message: string;
+  readonly scope?: OpenApiConfigScope;
+}
+
+const DIAG_SCOPE_GENERATION = "AVM-OPENAPI-001";
+const DIAG_SCOPE_EXPOSURE = "AVM-OPENAPI-002";
+const DIAG_ROUTE_CONFLICT = "AVM-OPENAPI-003";
+const DIAG_INVALID_ANNOTATION_KEY = "AVM-OPENAPI-004";
+
+/**
+ * Validates that generation options (e.g. additionalProperties) are only at API scope.
+ */
+export function validateOpenApiGenerationScope(
+  scope: OpenApiConfigScope,
+  generation: OpenApiGenerationConfig,
+): OpenApiConfigDiagnostic[] {
+  const diagnostics: OpenApiConfigDiagnostic[] = [];
+  if (scope === "api") return diagnostics;
+  const hasGen =
+    generation.additionalProperties !== undefined &&
+    (typeof generation.additionalProperties === "boolean" ||
+      (typeof generation.additionalProperties === "object" && generation.additionalProperties !== null));
+  if (hasGen) {
+    diagnostics.push({
+      code: DIAG_SCOPE_GENERATION,
+      message: "OpenAPI generation options (e.g. additionalProperties) are allowed at API scope only.",
+      scope,
+    });
+  }
+  return diagnostics;
+}
+
+/**
+ * Validates that exposure options (jsonPath, swaggerPath, scalar) are only at API scope.
+ */
+export function validateOpenApiExposureScope(
+  scope: OpenApiConfigScope,
+  exposure: OpenApiExposureConfig,
+): OpenApiConfigDiagnostic[] {
+  const diagnostics: OpenApiConfigDiagnostic[] = [];
+  if (scope === "api") return diagnostics;
+  const hasExposure =
+    exposure.jsonPath !== undefined ||
+    exposure.swaggerPath !== undefined ||
+    exposure.scalar !== undefined;
+  if (hasExposure) {
+    diagnostics.push({
+      code: DIAG_SCOPE_EXPOSURE,
+      message: "OpenAPI exposure options (jsonPath, swaggerPath, scalar) are allowed at API scope only.",
+      scope,
+    });
+  }
+  return diagnostics;
+}
+
+/**
+ * Collects exposure route paths and detects conflicts (same path, different mode).
+ */
+export interface ExposureRouteEntry {
+  readonly path: string;
+  readonly mode: "json" | "swagger" | "scalar";
+}
+
+export function collectExposureRoutes(exposure: OpenApiExposureConfig): ExposureRouteEntry[] {
+  const entries: ExposureRouteEntry[] = [];
+  if (exposure.jsonPath && typeof exposure.jsonPath === "string") {
+    entries.push({ path: exposure.jsonPath, mode: "json" });
+  }
+  if (exposure.swaggerPath && typeof exposure.swaggerPath === "string") {
+    entries.push({ path: exposure.swaggerPath, mode: "swagger" });
+  }
+  if (exposure.scalar && typeof exposure.scalar === "object" && exposure.scalar.path) {
+    entries.push({ path: exposure.scalar.path, mode: "scalar" });
+  }
+  return entries;
+}
+
+/**
+ * Detects route conflicts: same path used for more than one exposure mode.
+ */
+export function validateOpenApiExposureRouteConflicts(
+  exposure: OpenApiExposureConfig,
+): OpenApiConfigDiagnostic[] {
+  const routes = collectExposureRoutes(exposure);
+  const byPath = new Map<string, string[]>();
+  for (const { path, mode } of routes) {
+    const normalized = path.toLowerCase().replace(/\/+$/, "") || "/";
+    const list = byPath.get(normalized) ?? [];
+    list.push(mode);
+    byPath.set(normalized, list);
+  }
+  const diagnostics: OpenApiConfigDiagnostic[] = [];
+  for (const [path, modes] of byPath) {
+    if (modes.length > 1) {
+      diagnostics.push({
+        code: DIAG_ROUTE_CONFLICT,
+        message: `OpenAPI exposure route conflict: path "${path}" used for multiple modes: ${[...new Set(modes)].join(", ")}`,
+      });
+    }
+  }
+  return diagnostics;
+}
+
+/**
+ * Filters raw annotation keys to Effect-supported set; emits diagnostic for unsupported keys.
+ */
+export function filterAnnotationKeys(
+  raw: Record<string, unknown>,
+): { annotations: OpenApiAnnotationsConfig; diagnostics: OpenApiConfigDiagnostic[] } {
+  const annotations: OpenApiAnnotationsConfig = {};
+  const diagnostics: OpenApiConfigDiagnostic[] = [];
+  for (const [key, value] of Object.entries(raw)) {
+    if (OPENAPI_ANNOTATION_KEY_SET.has(key)) {
+      (annotations as Record<string, unknown>)[key] = value;
+    } else {
+      diagnostics.push({
+        code: DIAG_INVALID_ANNOTATION_KEY,
+        message: `Unsupported OpenAPI annotation key: "${key}". Supported: ${OPENAPI_ANNOTATION_KEYS.join(", ")}`,
+      });
+    }
+  }
+  return { annotations, diagnostics };
+}
+
+/**
+ * Normalizes and validates OpenAPI config for API scope.
+ * Merges annotations, validates generation/exposure scope and route conflicts.
+ */
+export function normalizeOpenApiConfig(
+  scope: OpenApiConfigScope,
+  raw: {
+    annotations?: Record<string, unknown>;
+    generation?: OpenApiGenerationConfig;
+    exposure?: OpenApiExposureConfig;
+  },
+): { config: NormalizedOpenApiConfig; diagnostics: OpenApiConfigDiagnostic[] } {
+  const diagnostics: OpenApiConfigDiagnostic[] = [];
+
+  const { annotations: ann, diagnostics: annDiag } = filterAnnotationKeys(
+    (raw.annotations ?? {}) as Record<string, unknown>,
+  );
+  diagnostics.push(...annDiag);
+
+  const generation = raw.generation ?? {};
+  diagnostics.push(...validateOpenApiGenerationScope(scope, generation));
+
+  const exposure = raw.exposure ?? {};
+  diagnostics.push(...validateOpenApiExposureScope(scope, exposure));
+  if (scope === "api") {
+    diagnostics.push(...validateOpenApiExposureRouteConflicts(exposure));
+  }
+
+  const config: NormalizedOpenApiConfig = {
+    annotations: ann,
+    generation,
+    exposure,
+  };
+
+  return { config, diagnostics };
+}

package/src/internal/httpapiSort.ts

@@ -0,0 +1,39 @@
+/**
+ * Deterministic ordering for HttpApi discovery: paths, roles, and AST nodes.
+ * Centralizes stable sort so AST nodes and file roles have consistent order.
+ */
+
+import type { HttpApiTreeNode } from "./httpapiDescriptorTree.js";
+import {
+  compareHttpApiPathOrder,
+  normalizeHttpApiRelativePath,
+  sortHttpApiPaths,
+} from "./httpapiFileRoles.js";
+
+export { compareHttpApiPathOrder, normalizeHttpApiRelativePath, sortHttpApiPaths };
+
+function nodeOrderKey(n: HttpApiTreeNode): string {
+  switch (n.type) {
+    case "endpoint":
+      return n.path;
+    case "group":
+    case "pathless_directory":
+      return n.dirPath;
+    default:
+      return "";
+  }
+}
+
+/**
+ * Stable comparison for tree nodes (by path or dirPath).
+ */
+export function compareHttpApiTreeNodeOrder(a: HttpApiTreeNode, b: HttpApiTreeNode): number {
+  return compareHttpApiPathOrder(nodeOrderKey(a), nodeOrderKey(b));
+}
+
+/**
+ * Returns a new array of tree nodes in deterministic order.
+ */
+export function sortHttpApiTreeNodes(nodes: readonly HttpApiTreeNode[]): HttpApiTreeNode[] {
+  return [...nodes].sort(compareHttpApiTreeNodeOrder);
+}

package/src/internal/path.ts

@@ -0,0 +1,46 @@
+import { realpathSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve } from "node:path";
+
+export const toPosixPath = (path: string): string => path.replaceAll("\\", "/");
+
+/** Strip the extension from a path using extname; returns path unchanged if no extension. */
+export const stripScriptExtension = (path: string): string => {
+  const ext = extname(path);
+  return ext ? path.slice(0, -ext.length) : path;
+};
+
+export const resolveRelativePath = (baseDir: string, relativePath: string): string =>
+  toPosixPath(resolve(baseDir, relativePath));
+
+/**
+ * Resolves relativePath against baseDir and ensures the result stays under baseDir.
+ */
+export function resolvePathUnderBase(
+  baseDir: string,
+  relativePath: string,
+): { ok: true; path: string } | { ok: false; error: "path-escapes-base" } {
+  const baseAbs = resolve(baseDir);
+  const resolved = resolve(baseDir, relativePath);
+  const rel = relative(baseAbs, resolved);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return { ok: false, error: "path-escapes-base" };
+  }
+  return { ok: true, path: toPosixPath(resolved) };
+}
+
+export function pathIsUnderBase(baseDir: string, absolutePath: string): boolean {
+  let baseAbs: string;
+  let resolvedAbs: string;
+  try {
+    baseAbs = realpathSync(resolve(baseDir));
+    resolvedAbs = realpathSync(resolve(absolutePath));
+  } catch {
+    baseAbs = resolve(baseDir);
+    resolvedAbs = resolve(absolutePath);
+  }
+  const rel = relative(baseAbs, resolvedAbs);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return false;
+  }
+  return true;
+}

package/src/internal/resolveConfig.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolves a config field: raw value or yield* Config.
+ * Requires ConfigProvider when value is Config.
+ */
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+
+export function resolveConfig<T>(
+  value: T | Config.Config<T> | undefined,
+  def: T,
+): Effect.Effect<T, Config.ConfigError> {
+  if (value === undefined) return Effect.succeed(def);
+  if (Config.isConfig(value)) return value.asEffect();
+  return Effect.succeed(value);
+}