@typed/app 1.0.0-beta.1

package/src/RouterVirtualModulePlugin.ts

@@ -0,0 +1,242 @@
+import { readdirSync, statSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import {
+  buildRouteDescriptors,
+  type RouteContractViolation,
+} from "./internal/buildRouteDescriptors.js";
+import { emitRouterMatchSource } from "./internal/emitRouterSource.js";
+import {
+  pathIsUnderBase,
+  resolvePathUnderBase,
+  resolveRelativePath,
+  toPosixPath,
+} from "./internal/path.js";
+import { validateNonEmptyString, validatePathSegment } from "./internal/validation.js";
+import type { VirtualModuleBuildError, VirtualModulePlugin } from "@typed/virtual-modules";
+import { ROUTER_TYPE_TARGET_SPECS } from "./internal/typeTargetSpecs.js";
+
+const DEFAULT_PREFIX = "router:";
+const DEFAULT_PLUGIN_NAME = "router-virtual-module";
+
+/** Extensions that count as route/script files when checking if a directory should resolve. */
+const SCRIPT_EXTENSION_SET = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mts",
+  ".cts",
+  ".mjs",
+  ".cjs",
+]);
+
+/** Glob patterns for discovering route files. */
+const ROUTE_FILE_GLOBS: readonly string[] = [
+  "**/*.ts",
+  "**/*.tsx",
+  "**/*.js",
+  "**/*.jsx",
+  "**/*.mts",
+  "**/*.cts",
+  "**/*.mjs",
+  "**/*.cjs",
+];
+
+export interface RouterVirtualModulePluginOptions {
+  readonly prefix?: string;
+  readonly name?: string;
+}
+
+export type ParseRouterVirtualModuleIdResult =
+  | { readonly ok: true; readonly relativeDirectory: string }
+  | { readonly ok: false; readonly reason: string };
+
+export function parseRouterVirtualModuleId(
+  id: string,
+  prefix: string = DEFAULT_PREFIX,
+): ParseRouterVirtualModuleIdResult {
+  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 ResolveRouterTargetDirectoryResult =
+  | { readonly ok: true; readonly targetDirectory: string }
+  | { readonly ok: false; readonly reason: string };
+
+export function resolveRouterTargetDirectory(
+  id: string,
+  importer: string,
+  prefix: string = DEFAULT_PREFIX,
+): ResolveRouterTargetDirectoryResult {
+  const parsed = parseRouterVirtualModuleId(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) };
+}
+
+function isExistingDirectory(absolutePath: string): boolean {
+  try {
+    return statSync(absolutePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function directoryHasScriptFiles(dir: string): boolean {
+  try {
+    const items = readdirSync(dir, { withFileTypes: true });
+    for (const e of items) {
+      if (
+        e.isFile() &&
+        SCRIPT_EXTENSION_SET.has(extname(e.name).toLowerCase()) &&
+        !e.name.toLowerCase().endsWith(".d.ts")
+      )
+        return true;
+      if (e.isDirectory() && directoryHasScriptFiles(join(dir, e.name))) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+const FAIL_ORDER: RouteContractViolation["code"][] = [
+  "RVM-AMBIGUOUS-001",
+  "RVM-GUARD-001",
+  "RVM-CATCH-001",
+  "RVM-DEPS-001",
+  "RVM-KIND-001",
+];
+
+function failOnViolations(
+  violations: readonly RouteContractViolation[],
+  toDiagnostic: (v: RouteContractViolation) => {
+    code: string;
+    message: string;
+    pluginName: string;
+  },
+): VirtualModuleBuildError | null {
+  for (const code of FAIL_ORDER) {
+    const found = violations.filter((v) => v.code === code);
+    if (found.length > 0) return { errors: found.map(toDiagnostic) };
+  }
+  return null;
+}
+
+export const createRouterVirtualModulePlugin = (
+  options: RouterVirtualModulePluginOptions = {},
+): VirtualModulePlugin => {
+  const prefix = options.prefix ?? DEFAULT_PREFIX;
+  const name = options.name ?? DEFAULT_PLUGIN_NAME;
+
+  return {
+    name,
+    typeTargetSpecs: ROUTER_TYPE_TARGET_SPECS,
+    shouldResolve(id, importer) {
+      const resolved = resolveRouterTargetDirectory(id, importer, prefix);
+      if (!resolved.ok) return false;
+      if (!isExistingDirectory(resolved.targetDirectory)) return false;
+      return directoryHasScriptFiles(resolved.targetDirectory);
+    },
+    build(id, importer, api) {
+      const resolved = resolveRouterTargetDirectory(id, importer, prefix);
+      if (!resolved.ok) {
+        return {
+          errors: [{ code: "RVM-ID-001", message: resolved.reason, pluginName: name }],
+        } satisfies VirtualModuleBuildError;
+      }
+      if (!isExistingDirectory(resolved.targetDirectory)) {
+        return {
+          errors: [
+            {
+              code: "RVM-DISC-001",
+              message: `target directory does not exist: ${resolveRelativePath(dirname(importer), resolved.targetDirectory)}`,
+              pluginName: name,
+            },
+          ],
+        } satisfies VirtualModuleBuildError;
+      }
+
+      const snapshots = api.directory(ROUTE_FILE_GLOBS, {
+        baseDir: resolved.targetDirectory,
+        recursive: true,
+        watch: true,
+      });
+      const {
+        descriptors,
+        violations,
+        guardExportByPath,
+        catchExportByPath,
+        catchFormByPath,
+        depsFormByPath,
+      } = buildRouteDescriptors(snapshots, resolved.targetDirectory, api);
+
+      const toDiagnostic = (v: RouteContractViolation) => ({
+        code: v.code,
+        message: v.message,
+        pluginName: name,
+      });
+
+      const err = failOnViolations(violations, toDiagnostic);
+      if (err) return err;
+
+      if (descriptors.length === 0) {
+        if (violations.length > 0) {
+          return { errors: violations.map(toDiagnostic) };
+        }
+        return {
+          errors: [
+            {
+              code: "RVM-LEAF-001",
+              message: `no valid route leaves discovered in ${resolved.targetDirectory}`,
+              pluginName: name,
+            },
+          ],
+        };
+      }
+
+      return emitRouterMatchSource(
+        descriptors,
+        resolved.targetDirectory,
+        importer,
+        guardExportByPath,
+        catchExportByPath,
+        catchFormByPath,
+        depsFormByPath,
+      );
+    },
+  };
+};

package/src/createTypeInfoApiSessionForApp.ts

@@ -0,0 +1,57 @@
+import type { CreateTypeInfoApiSessionOptions, TypeTargetSpec } from "@typed/virtual-modules";
+import {
+  createTypeInfoApiSession,
+  createTypeTargetBootstrapContent,
+} from "@typed/virtual-modules";
+import { HTTPAPI_TYPE_TARGET_SPECS, ROUTER_TYPE_TARGET_SPECS } from "./internal/typeTargetSpecs.js";
+
+/** Merged type target specs for router + HttpApi plugins. Dedupes by id. */
+const APP_TYPE_TARGET_SPECS: readonly TypeTargetSpec[] = (() => {
+  const seen = new Set<string>();
+  const out: TypeTargetSpec[] = [];
+  for (const spec of [...ROUTER_TYPE_TARGET_SPECS, ...HTTPAPI_TYPE_TARGET_SPECS]) {
+    if (!seen.has(spec.id)) {
+      seen.add(spec.id);
+      out.push(spec);
+    }
+  }
+  return out;
+})();
+
+/** Bootstrap content for app type targets. Include in program rootNames when creating programs. */
+export const APP_TYPE_TARGET_BOOTSTRAP_CONTENT = createTypeTargetBootstrapContent(
+  APP_TYPE_TARGET_SPECS,
+);
+
+/**
+ * Creates a TypeInfo API session with type target specs for router and HttpApi
+ * virtual modules. Use when providing createTypeInfoApiSession to typedVitePlugin
+ * or other integrations that need structural assignability (assignableTo) checks.
+ *
+ * The program must include imports from canonical type target modules (effect/Effect,
+ * @typed/router, etc.). If the program has no such imports, add a bootstrap file:
+ * write APP_TYPE_TARGET_BOOTSTRAP_CONTENT to a file and include it in rootNames.
+ *
+ * @example
+ * ```ts
+ * import { createTypeInfoApiSessionForApp, APP_TYPE_TARGET_BOOTSTRAP_CONTENT } from "@typed/app";
+ * import { writeFileSync } from "node:fs";
+ * import { join } from "node:path";
+ * import ts from "typescript";
+ *
+ * const bootstrapPath = join(tmpDir, "__typeTargetBootstrap.ts");
+ * writeFileSync(bootstrapPath, APP_TYPE_TARGET_BOOTSTRAP_CONTENT);
+ * const program = ts.createProgram(["src/main.ts", bootstrapPath], options, host);
+ * typedVitePlugin({
+ *   createTypeInfoApiSession: () => createTypeInfoApiSessionForApp({ ts, program }),
+ * });
+ * ```
+ */
+export function createTypeInfoApiSessionForApp(
+  options: Omit<CreateTypeInfoApiSessionOptions, "typeTargetSpecs">,
+) {
+  return createTypeInfoApiSession({
+    ...options,
+    typeTargetSpecs: APP_TYPE_TARGET_SPECS,
+  });
+}

package/src/defineApiHandler.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Tests for defineApiHandler: runtime behavior and compile-time positive/negative typing.
+ * Handler receives { path, query, headers, body }; schemas optional (headers, body, success, error).
+ * @see .docs/specs/httpapi-virtual-module-plugin/testing-strategy.md (TS-15)
+ */
+
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { describe, expect, it } from "vitest";
+import * as Route from "@typed/router/Route";
+import { defineApiHandler } from "./httpapi/defineApiHandler.js";
+
+describe("defineApiHandler", () => {
+  const route = Route.Join(Route.Parse("users"), Route.Param("id"));
+  const schemas = {
+    headers: Schema.Struct({ requestId: Schema.String }),
+    body: Schema.Struct({ name: Schema.String }),
+    success: Schema.Struct({ ok: Schema.Boolean, id: Schema.String }),
+    error: Schema.Struct({ code: Schema.String, message: Schema.String }),
+  };
+
+  it("returns handler in curried form and preserves identity", () => {
+    const handler = defineApiHandler(route, "GET", schemas)((ctx) =>
+      Effect.succeed({ ok: true, id: ctx.path.id }),
+    );
+    expect(typeof handler).toBe("function");
+  });
+
+  it("handler context has typed path, query, headers, body", () => {
+    const handler = defineApiHandler(route, "GET", schemas)((ctx) => {
+      const _path = ctx.path;
+      const _query: Record<string, string | string[] | undefined> = ctx.query;
+      const _body: { name: string } = ctx.body;
+      const _headers: { requestId: string } = ctx.headers;
+      return Effect.succeed({
+        ok: true,
+        id: _path.id,
+      });
+    });
+    expect(handler).toBeDefined();
+  });
+
+  it("handler return type is Effect<Success, Error>", () => {
+    const handler = defineApiHandler(route, "POST", schemas)((ctx) =>
+      Effect.succeed({ ok: true, id: ctx.path.id }),
+    );
+    const run = Effect.runPromise(
+      handler({
+        path: { id: "1" },
+        query: {},
+        body: { name: "x" },
+        headers: { requestId: "r-1" },
+      }),
+    );
+    return run.then((v) => {
+      expect(v).toEqual({ ok: true, id: "1" });
+    });
+  });
+
+  it("accepts Router.Route from Parse for simple path", () => {
+    const route = Route.Parse("status");
+    const handler = defineApiHandler(route, "GET")(() =>
+      Effect.succeed({ status: "ok" }),
+    );
+    const run = Effect.runPromise(
+      handler({
+        path: {},
+        query: {},
+        body: undefined,
+        headers: {},
+      }),
+    );
+    return run.then((v) => expect(v).toEqual({ status: "ok" }));
+  });
+});
+
+describe("defineApiHandler compile-time negative tests", () => {
+  const route = Route.Join(Route.Parse("users"), Route.Param("id"));
+  const schemas = {
+    headers: Schema.Struct({ requestId: Schema.String }),
+    body: Schema.Struct({ name: Schema.String }),
+    success: Schema.Struct({ ok: Schema.Boolean }),
+    error: Schema.Struct({ code: Schema.String }),
+  };
+
+  it("rejects handler returning wrong success shape (ts-expect-error)", () => {
+    defineApiHandler(route, "GET", schemas)(
+      // @ts-expect-error invalid return type
+      () => Effect.succeed(42),
+    );
+  });
+
+  it("rejects handler using wrong path shape (ts-expect-error)", () => {
+    defineApiHandler(route, "GET", schemas)((ctx) => {
+      // @ts-expect-error - ctx.path is { id: string }; number is not assignable to string
+      const _wrong: { id: number } = ctx.path;
+      return Effect.succeed({ ok: true });
+    });
+  });
+});

package/src/httpapi/defineApiHandler.ts

@@ -0,0 +1,141 @@
+/**
+ * Typed handler helper for HttpApi endpoint contracts.
+ * Uses Router.Route from @typed/router (Router.Parse, Route.Join, etc.) for type-safe path/query.
+ * Curried form: defineApiHandler(route, method, schemas?)(handler)
+ * Handler receives { path, query, headers, body } for type-safe decoding;
+ * error/success schemas encode response payloads into HttpServerResponse with annotated status codes.
+ * Structural type checking: handler return must match success schema; errors must match error schema.
+ *
+ * @see .docs/specs/httpapi-virtual-module-plugin/spec.md (Typed handler helper)
+ */
+
+import type * as Effect from "effect/Effect";
+import type * as Schema from "effect/Schema";
+import type { HttpMethod as EffectHttpMethod } from "effect/unstable/http/HttpMethod";
+import type * as Route from "@typed/router";
+
+/** Re-export Effect HttpMethod for helper consumers. */
+export type HttpMethod = EffectHttpMethod;
+
+/** Typed empty record for path params and headers when none are defined. Used by emitted handler adapter. */
+export const emptyRecordString: Record<string, string> = {};
+
+/** Typed empty record for query params when none are defined. Used by emitted handler adapter. */
+export const emptyRecordStringArray: Record<string, string | string[] | undefined> = {};
+
+/** Route MUST be Router.Route (from Router.Parse, Route.Join, Route.Param, etc.). */
+export type ApiRoute = Route.Route.Any;
+
+/**
+ * Infers handler params from endpoint contract. Use with handler:
+ * handler: (params: ApiHandlerParams<{ route, method?, success?, error?, headers?, body? }>) => Effect
+ */
+export type ApiHandlerParams<
+  T extends {
+    readonly route: ApiRoute;
+    readonly method: HttpMethod | "*";
+    readonly success?: Schema.Schema<any>;
+    readonly error?: Schema.Schema<any>;
+    readonly headers?: Schema.Schema<any>;
+    readonly body?: Schema.Schema<any>;
+  },
+> = {
+  readonly path: Route.Route.PathType<T["route"]>;
+  readonly query: Route.Route.QueryType<T["route"]>;
+  readonly headers: T["headers"] extends Schema.Schema<infer H> ? H : Record<string, string>;
+  readonly body: T["body"] extends Schema.Schema<infer B> ? B : unknown;
+};
+
+/**
+ * Optional schemas: headers, body (request decoders); error, success (response encoders).
+ * Use HttpApiSchema.status(code)(schema) to annotate status codes, e.g.:
+ * success: HttpApiSchema.status(200)(Schema.Struct({ ok: Schema.Boolean }))
+ * error: HttpApiSchema.status(400)(Schema.Struct({ message: Schema.String }))
+ */
+export interface EndpointSchemas<
+  THeaders = unknown,
+  TBody = unknown,
+  TSuccess = unknown,
+  TError = unknown,
+> {
+  readonly headers?: Schema.Schema<THeaders>;
+  readonly body?: Schema.Schema<TBody>;
+  readonly success?: Schema.Schema<TSuccess>;
+  readonly error?: Schema.Schema<TError>;
+}
+
+/** Handler context: path params, query, headers, body (mirrors HttpServerRequest decoders). */
+export interface ApiHandlerContext<
+  TPath = Record<string, string>,
+  TQuery = Record<string, string | string[] | undefined>,
+  THeaders = Record<string, string>,
+  TBody = unknown,
+> {
+  readonly path: TPath;
+  readonly query: TQuery;
+  readonly headers: THeaders;
+  readonly body: TBody;
+}
+
+/** Handler function type: context -> Effect<Success, Error, Requirements> */
+export type ApiHandlerFn<
+  TPath = Record<string, string>,
+  TQuery = Record<string, string | string[] | undefined>,
+  THeaders = Record<string, string>,
+  TBody = unknown,
+  TSuccess = unknown,
+  TError = unknown,
+  Requirements = never,
+> = (
+  ctx: ApiHandlerContext<TPath, TQuery, THeaders, TBody>,
+) => Effect.Effect<TSuccess, TError, Requirements>;
+
+/** Typed handler as returned by defineApiHandler */
+export type TypedApiHandler<
+  TPath = Record<string, string>,
+  TQuery = Record<string, string | string[] | undefined>,
+  THeaders = Record<string, string>,
+  TBody = unknown,
+  TSuccess = unknown,
+  TError = unknown,
+  Requirements = never,
+> = ApiHandlerFn<TPath, TQuery, THeaders, TBody, TSuccess, TError, Requirements>;
+
+/**
+ * Curried helper: (route, method, schemas?) => (handler) => typed handler.
+ * Route MUST be Router.Route (Router.Parse, Route.Join, Route.Param, etc.).
+ * Enforces at compile time that the handler receives { path, query, headers, body }
+ * and returns Effect<Success, Error> compatible with success/error schemas.
+ */
+export function defineApiHandler<
+  TRoute extends ApiRoute,
+  Method extends HttpMethod,
+  THeaders = Record<string, string>,
+  TBody = unknown,
+  TSuccess = unknown,
+  TError = unknown,
+>(
+  _route: TRoute,
+  _method: Method,
+  _schemas?: EndpointSchemas<THeaders, TBody, TSuccess, TError>,
+): <Requirements = never>(
+  handler: ApiHandlerFn<
+    Route.Route.PathType<TRoute>,
+    Route.Route.QueryType<TRoute>,
+    THeaders,
+    TBody,
+    TSuccess,
+    TError,
+    Requirements
+  >,
+) => TypedApiHandler<
+  Route.Route.PathType<TRoute>,
+  Route.Route.QueryType<TRoute>,
+  THeaders,
+  TBody,
+  TSuccess,
+  TError,
+  Requirements
+> {
+  return (handler) => handler;
+}

package/src/httpapiDescriptorTree.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { buildHttpApiDescriptorTree, isPathlessDirectorySegment } from "./internal/httpapiDescriptorTree.js";
+import { classifyHttpApiFileRole } from "./internal/httpapiFileRoles.js";
+
+function rolesFromPaths(paths: string[]) {
+  return paths.map((p) => classifyHttpApiFileRole(p));
+}
+
+describe("httpapiDescriptorTree", () => {
+  describe("isPathlessDirectorySegment", () => {
+    it("returns true for parenthesized segments", () => {
+      expect(isPathlessDirectorySegment("(internal)")).toBe(true);
+      expect(isPathlessDirectorySegment("(admin-internal)")).toBe(true);
+    });
+    it("returns false for normal segments", () => {
+      expect(isPathlessDirectorySegment("users")).toBe(false);
+      expect(isPathlessDirectorySegment("audits")).toBe(false);
+    });
+  });
+
+  describe("buildHttpApiDescriptorTree", () => {
+    it("builds empty root when no supported roles", () => {
+      const tree = buildHttpApiDescriptorTree({
+        roles: rolesFromPaths(["_api.ts"]),
+      });
+      expect(tree.type).toBe("api_root");
+      expect(tree.dirPath).toBe("");
+      expect(tree.children).toEqual([]);
+      expect(tree.conventions).toHaveLength(1);
+      expect(tree.conventions[0]).toEqual({ path: "_api.ts", kind: "api_root" });
+      expect(tree.diagnostics).toHaveLength(0);
+    });
+
+    it("collects unsupported_reserved into diagnostics", () => {
+      const tree = buildHttpApiDescriptorTree({
+        roles: rolesFromPaths(["_api.ts", "list.d.ts"]),
+      });
+      expect(tree.diagnostics).toHaveLength(1);
+      expect(tree.diagnostics[0].code).toBe("HTTPAPI-ROLE-001");
+      expect(tree.diagnostics[0].path).toBe("list.d.ts");
+    });
+
+    it("builds one group with one endpoint", () => {
+      const tree = buildHttpApiDescriptorTree({
+        roles: rolesFromPaths([
+          "_api.ts",
+          "users/_group.ts",
+          "users/list.ts",
+        ]),
+      });
+      expect(tree.children).toHaveLength(1);
+      const group = tree.children[0];
+      expect(group?.type).toBe("group");
+      if (group?.type !== "group") return;
+      expect(group.groupName).toBe("users");
+      expect(group.dirPath).toBe("users");
+      expect(group.children).toHaveLength(1);
+      const ep = group.children[0];
+      expect(ep?.type).toBe("endpoint");
+      if (ep?.type !== "endpoint") return;
+      expect(ep.path).toBe("users/list.ts");
+      expect(ep.stem).toBe("list");
+      expect(ep.companions).toHaveLength(0);
+    });
+
+    it("attaches endpoint companions to endpoint node", () => {
+      const tree = buildHttpApiDescriptorTree({
+        roles: rolesFromPaths([
+          "users/list.ts",
+          "users/list.openapi.ts",
+          "users/list.dependencies.ts",
+        ]),
+      });
+      const group = tree.children[0];
+      expect(group?.type).toBe("group");
+      if (group?.type !== "group") return;
+      const ep = group.children[0];
+      expect(ep?.type).toBe("endpoint");
+      if (ep?.type !== "endpoint") return;
+      expect(ep.companions).toHaveLength(2);
+      const kinds = ep.companions.map((c) => c.kind).sort();
+      expect(kinds).toEqual([".dependencies", ".openapi"]);
+    });
+
+    it("pathless directory does not create a named group", () => {
+      const tree = buildHttpApiDescriptorTree({
+        roles: rolesFromPaths([
+          "(internal)/_prefix.ts",
+          "(internal)/audits/_group.ts",
+          "(internal)/audits/list.ts",
+        ]),
+      });
+      expect(tree.children).toHaveLength(1);
+      const pathless = tree.children[0];
+      expect(pathless?.type).toBe("pathless_directory");
+      if (pathless?.type !== "pathless_directory") return;
+      expect(pathless.dirPath).toBe("(internal)");
+      expect(pathless.conventions).toEqual([
+        {
+          path: "(internal)/_prefix.ts",
+          kind: "_prefix.ts",
+        },
+      ]);
+      expect(pathless.children).toHaveLength(1);
+      const group = pathless.children[0];
+      expect(group?.type).toBe("group");
+      if (group?.type !== "group") return;
+      expect(group.groupName).toBe("audits");
+      expect(group.dirPath).toBe("(internal)/audits");
+    });
+
+    it("deterministic ordering of children", () => {
+      const tree = buildHttpApiDescriptorTree({
+        roles: rolesFromPaths([
+          "z/z.ts",
+          "a/a.ts",
+          "users/list.ts",
+        ]),
+      });
+      const names = tree.children.map((c) => (c.type === "group" || c.type === "pathless_directory" ? c.dirPath : c.path));
+      expect(names).toEqual(["a", "users", "z"]);
+    });
+  });
+});