@typed/app 1.0.0-beta.1

package/dist/internal/buildRouteDescriptors.js

@@ -0,0 +1,371 @@
+import { basename, dirname, join, relative } from "node:path";
+import { stripScriptExtension, toPosixPath } from "./path.js";
+import { classifyCatchForm, classifyDepsExport, getCallableReturnType, isCallableNode, typeNodeExpectsRefSubjectParam, typeNodeIsEffectOptionReturn, typeNodeIsRouteCompatible, typeNodeToRuntimeKind, } from "./routeTypeNode.js";
+const ENTRYPOINT_EXPORTS = ["handler", "template", "default"];
+const COMPANION_SUFFIXES = [".guard.ts", ".dependencies.ts", ".layout.ts", ".catch.ts"];
+const DIRECTORY_COMPANIONS = new Set(["_guard.ts", "_dependencies.ts", "_layout.ts", "_catch.ts"]);
+const GUARD_EXPORT_NAMES = ["default", "guard"];
+const CATCH_EXPORT_NAMES = ["catch", "catchFn"];
+function isEntryPointExport(name) {
+    return ENTRYPOINT_EXPORTS.includes(name);
+}
+function isGuardExportName(name) {
+    return GUARD_EXPORT_NAMES.includes(name);
+}
+function isCatchExportName(name) {
+    return CATCH_EXPORT_NAMES.includes(name);
+}
+const COMPANION_KIND_TO_SUFFIX = {
+    guard: ".guard.ts",
+    dependencies: ".dependencies.ts",
+    layout: ".layout.ts",
+    catch: ".catch.ts",
+};
+const COMPANION_KIND_TO_DIRECTORY_FILE = {
+    guard: "_guard.ts",
+    dependencies: "_dependencies.ts",
+    layout: "_layout.ts",
+    catch: "_catch.ts",
+};
+function isCompanionModulePath(absolutePath) {
+    const fileName = basename(toPosixPath(absolutePath));
+    if (DIRECTORY_COMPANIONS.has(fileName))
+        return true;
+    return COMPANION_SUFFIXES.some((suffix) => fileName.endsWith(suffix));
+}
+function listEntrypointExports(snapshot) {
+    return snapshot.exports.filter((value) => ENTRYPOINT_EXPORTS.some((entrypointName) => entrypointName === value.name));
+}
+function isRouteExportCompatible(routeExport, api) {
+    return typeNodeIsRouteCompatible(routeExport.type, api);
+}
+function classifyEntrypointKind(entrypoint, api) {
+    const { type } = entrypoint;
+    const nodeForKind = isCallableNode(type) ? (getCallableReturnType(type) ?? type) : type;
+    return typeNodeToRuntimeKind(nodeForKind, api);
+}
+function getEntryPointName(entrypoint, relPath) {
+    if (!isEntryPointExport(entrypoint.name)) {
+        return {
+            ok: false,
+            violation: {
+                code: "RVM-ENTRY-003",
+                message: `invalid entrypoint export name ${JSON.stringify(entrypoint.name)} in ${relPath}`,
+            },
+        };
+    }
+    return { ok: true, value: entrypoint.name };
+}
+function resolveComposedConcernsForLeaf(leafFilePath, existingPaths) {
+    const leafDir = dirname(leafFilePath);
+    const leafBaseName = basename(stripScriptExtension(leafFilePath));
+    const ancestorDirs = [""];
+    if (leafDir !== "." && leafDir !== "") {
+        const segments = leafDir.split("/").filter(Boolean);
+        let acc = "";
+        for (const seg of segments) {
+            acc = acc ? `${acc}/${seg}` : seg;
+            ancestorDirs.push(acc);
+        }
+    }
+    const collectForKind = (kind) => {
+        const result = [];
+        for (const d of [...ancestorDirs].reverse()) {
+            const dirPath = d === "."
+                ? COMPANION_KIND_TO_DIRECTORY_FILE[kind]
+                : join(d, COMPANION_KIND_TO_DIRECTORY_FILE[kind]);
+            const normal = toPosixPath(dirPath);
+            if (existingPaths.has(normal))
+                result.push(normal);
+        }
+        const siblingPath = leafDir === "."
+            ? `${leafBaseName}${COMPANION_KIND_TO_SUFFIX[kind]}`
+            : toPosixPath(join(leafDir, `${leafBaseName}${COMPANION_KIND_TO_SUFFIX[kind]}`));
+        if (existingPaths.has(siblingPath))
+            result.push(siblingPath);
+        return result;
+    };
+    return {
+        guard: collectForKind("guard"),
+        dependencies: collectForKind("dependencies"),
+        layout: collectForKind("layout"),
+        catch: collectForKind("catch"),
+    };
+}
+/**
+ * Sibling companion path for a leaf file (e.g. "nested/Y.tsx" + "layout" → "nested/Y.layout.ts").
+ */
+export function siblingCompanionPath(leafFilePath, kind) {
+    const dir = dirname(leafFilePath);
+    const base = basename(stripScriptExtension(leafFilePath));
+    const file = kind === "dependencies" ? `${base}.dependencies.ts` : `${base}.${kind}.ts`;
+    return dir ? toPosixPath(join(dir, file)) : file;
+}
+/**
+ * Build route descriptors and validate guards, catches, and dependencies from type info snapshots.
+ */
+export function buildRouteDescriptors(snapshots, baseDir, api) {
+    const descriptors = [];
+    const violations = [];
+    const existingPaths = new Set(snapshots.map((s) => toPosixPath(relative(baseDir, s.filePath))));
+    for (const snapshot of snapshots) {
+        if (isCompanionModulePath(snapshot.filePath))
+            continue;
+        const entrypoints = listEntrypointExports(snapshot);
+        const routeExport = snapshot.exports.find((value) => value.name === "route");
+        if (!routeExport) {
+            if (entrypoints.length > 0) {
+                violations.push({
+                    code: "RVM-ROUTE-001",
+                    message: `missing "route" export in ${toPosixPath(relative(baseDir, snapshot.filePath))}`,
+                });
+            }
+            continue;
+        }
+        if (!isRouteExportCompatible(routeExport, api)) {
+            violations.push({
+                code: "RVM-ROUTE-002",
+                message: `route export is not structurally compatible with Route in ${toPosixPath(relative(baseDir, snapshot.filePath))}`,
+            });
+            continue;
+        }
+        if (entrypoints.length === 0) {
+            violations.push({
+                code: "RVM-ENTRY-001",
+                message: `expected one of handler|template|default in ${toPosixPath(relative(baseDir, snapshot.filePath))}`,
+            });
+            continue;
+        }
+        if (entrypoints.length > 1) {
+            violations.push({
+                code: "RVM-ENTRY-002",
+                message: `multiple entrypoint exports found in ${toPosixPath(relative(baseDir, snapshot.filePath))}`,
+            });
+            continue;
+        }
+        const entrypoint = entrypoints[0];
+        const relPath = toPosixPath(relative(baseDir, snapshot.filePath));
+        const entrypointNameResult = getEntryPointName(entrypoint, relPath);
+        if (!entrypointNameResult.ok) {
+            violations.push(entrypointNameResult.violation);
+            continue;
+        }
+        const runtimeKind = classifyEntrypointKind(entrypoint, api);
+        if (runtimeKind === "unknown") {
+            violations.push({
+                code: "RVM-KIND-001",
+                message: `handler/template/default runtime kind could not be determined (type targets missing). Ensure route files import from @typed/fx, effect, etc. in ${relPath}`,
+            });
+            continue;
+        }
+        const entrypointIsFunction = isCallableNode(entrypoint.type);
+        const entrypointExpectsRefSubject = entrypointIsFunction &&
+            typeNodeExpectsRefSubjectParam(entrypoint.type, api);
+        const composedConcerns = resolveComposedConcernsForLeaf(relPath, existingPaths);
+        const inFileConcerns = {};
+        for (const name of ["layout", "dependencies", "catch", "guard"]) {
+            if (snapshot.exports.some((e) => e.name === name))
+                inFileConcerns[name] = true;
+        }
+        descriptors.push({
+            filePath: relPath,
+            entrypointExport: entrypointNameResult.value,
+            runtimeKind,
+            entrypointIsFunction,
+            entrypointExpectsRefSubject,
+            composedConcerns,
+            inFileConcerns,
+            routeTypeText: routeExport.type.text,
+        });
+    }
+    const sortedDescriptors = [...descriptors].sort((left, right) => left.filePath.localeCompare(right.filePath));
+    const seenRouteIdentity = new Map();
+    const ambiguousViolations = [];
+    const dedupedDescriptors = [];
+    for (const d of sortedDescriptors) {
+        const typeKey = d.routeTypeText.replace(/\s+/g, " ").trim();
+        const key = `${d.filePath}:${typeKey}`;
+        const firstSeen = seenRouteIdentity.get(key);
+        if (firstSeen !== undefined) {
+            ambiguousViolations.push({
+                code: "RVM-AMBIGUOUS-001",
+                message: `ambiguous route: same type as ${firstSeen}, also in ${d.filePath}`,
+            });
+            continue;
+        }
+        seenRouteIdentity.set(key, d.filePath);
+        dedupedDescriptors.push(d);
+    }
+    const guardViolations = [];
+    const guardExportByPath = {};
+    const guardPaths = new Set();
+    for (const d of dedupedDescriptors) {
+        for (const p of d.composedConcerns.guard)
+            guardPaths.add(p);
+    }
+    for (const relPath of guardPaths) {
+        const snapshot = snapshots.find((s) => toPosixPath(relative(baseDir, s.filePath)) === relPath);
+        if (!snapshot)
+            continue;
+        const guardExport = snapshot.exports.find((e) => e.name === GUARD_EXPORT_NAMES[0]) ??
+            snapshot.exports.find((e) => e.name === GUARD_EXPORT_NAMES[1]);
+        if (!guardExport) {
+            guardViolations.push({
+                code: "RVM-GUARD-001",
+                message: `guard file must export "guard" or default: ${relPath}`,
+            });
+            continue;
+        }
+        if (!isCallableNode(guardExport.type)) {
+            guardViolations.push({
+                code: "RVM-GUARD-001",
+                message: `guard export must be a function (Effect<Option<*>, *, *>): ${relPath}`,
+            });
+            continue;
+        }
+        if (!typeNodeIsEffectOptionReturn(guardExport.type, api)) {
+            guardViolations.push({
+                code: "RVM-GUARD-001",
+                message: `guard return type must be Effect<Option<*>, *, *>: ${relPath}`,
+            });
+            continue;
+        }
+        if (!isGuardExportName(guardExport.name)) {
+            guardViolations.push({
+                code: "RVM-GUARD-001",
+                message: `guard export name ${JSON.stringify(guardExport.name)} not in [guard, default]: ${relPath}`,
+            });
+            continue;
+        }
+        guardExportByPath[relPath] = guardExport.name;
+    }
+    const catchExportByPath = {};
+    const catchFormByPath = {};
+    const depsFormByPath = {};
+    const catchPaths = new Set();
+    const catchViolations = [];
+    for (const d of dedupedDescriptors) {
+        for (const p of d.composedConcerns.catch)
+            catchPaths.add(p);
+    }
+    for (const relPath of catchPaths) {
+        const snapshot = snapshots.find((s) => toPosixPath(relative(baseDir, s.filePath)) === relPath);
+        if (!snapshot)
+            continue;
+        const catchExport = snapshot.exports.find((e) => e.name === CATCH_EXPORT_NAMES[0]) ??
+            snapshot.exports.find((e) => e.name === CATCH_EXPORT_NAMES[1]);
+        if (!catchExport) {
+            catchViolations.push({
+                code: "RVM-CATCH-001",
+                message: `catch file must export "catch" or "catchFn": ${relPath}`,
+            });
+            continue;
+        }
+        if (!isCatchExportName(catchExport.name)) {
+            catchViolations.push({
+                code: "RVM-CATCH-001",
+                message: `catch export name ${JSON.stringify(catchExport.name)} not in [catch, catchFn]: ${relPath}`,
+            });
+            continue;
+        }
+        const catchForm = classifyCatchForm(catchExport.type, api);
+        if (catchForm.returnKind === "unknown") {
+            catchViolations.push({
+                code: "RVM-KIND-001",
+                message: `catch return kind could not be determined (type targets missing): ${relPath}`,
+            });
+            continue;
+        }
+        catchExportByPath[relPath] = catchExport.name;
+        catchFormByPath[relPath] = catchForm;
+    }
+    for (const d of dedupedDescriptors) {
+        if (!d.inFileConcerns.catch)
+            continue;
+        const snapshot = snapshots.find((s) => toPosixPath(relative(baseDir, s.filePath)) === d.filePath);
+        if (!snapshot)
+            continue;
+        const catchExport = snapshot.exports.find((e) => e.name === CATCH_EXPORT_NAMES[0]) ??
+            snapshot.exports.find((e) => e.name === CATCH_EXPORT_NAMES[1]);
+        if (catchExport) {
+            if (!isCatchExportName(catchExport.name)) {
+                catchViolations.push({
+                    code: "RVM-CATCH-001",
+                    message: `catch export name ${JSON.stringify(catchExport.name)} not in [catch, catchFn]: ${d.filePath}`,
+                });
+                continue;
+            }
+            const catchForm = classifyCatchForm(catchExport.type, api);
+            if (catchForm.returnKind === "unknown") {
+                catchViolations.push({
+                    code: "RVM-KIND-001",
+                    message: `catch return kind could not be determined (type targets missing): ${d.filePath}`,
+                });
+            }
+            else {
+                catchExportByPath[d.filePath] = catchExport.name;
+                catchFormByPath[d.filePath] = catchForm;
+            }
+        }
+    }
+    const depsPaths = new Set();
+    for (const d of dedupedDescriptors) {
+        for (const p of d.composedConcerns.dependencies) {
+            if (basename(p).startsWith("_"))
+                depsPaths.add(p);
+        }
+    }
+    const depsViolations = [];
+    for (const relPath of depsPaths) {
+        const snapshot = snapshots.find((s) => toPosixPath(relative(baseDir, s.filePath)) === relPath);
+        if (!snapshot)
+            continue;
+        const defaultExport = snapshot.exports.find((e) => e.name === "default");
+        if (!defaultExport) {
+            depsViolations.push({
+                code: "RVM-DEPS-001",
+                message: `${relPath} is used as directory dependencies but has no default export. Export a default of type Layer, ServiceMap, or Array.`,
+            });
+            continue;
+        }
+        const kind = classifyDepsExport(defaultExport.type, api);
+        if (kind === "unknown") {
+            depsViolations.push({
+                code: "RVM-DEPS-001",
+                message: `${relPath} default export type could not be determined. Must be Layer, ServiceMap, or Array.`,
+            });
+            continue;
+        }
+        depsFormByPath[relPath] = kind;
+    }
+    const infileCompanionViolations = [];
+    for (const d of dedupedDescriptors) {
+        for (const kind of ["layout", "dependencies", "catch", "guard"]) {
+            if (!d.inFileConcerns[kind])
+                continue;
+            const siblingPath = siblingCompanionPath(d.filePath, kind);
+            if (d.composedConcerns[kind].includes(siblingPath)) {
+                infileCompanionViolations.push({
+                    code: "RVM-INFILE-COMPANION-001",
+                    message: `${d.filePath} exports "${kind}" in-file and has companion ${siblingPath}; in-file wins but this is ambiguous. Remove one.`,
+                });
+            }
+        }
+    }
+    const allViolations = [
+        ...violations,
+        ...ambiguousViolations,
+        ...guardViolations,
+        ...catchViolations,
+        ...depsViolations,
+        ...infileCompanionViolations,
+    ].sort((left, right) => left.message.localeCompare(right.message));
+    return {
+        descriptors: dedupedDescriptors,
+        violations: allViolations,
+        guardExportByPath,
+        catchExportByPath,
+        catchFormByPath,
+        depsFormByPath,
+    };
+}

package/dist/internal/emitHttpApiSource.d.ts

@@ -0,0 +1,18 @@
+import type { HttpApiDescriptorTree } from "./httpapiDescriptorTree.js";
+declare const OPTIONAL_ENDPOINT_EXPORTS: readonly ["headers", "body", "success", "error"];
+type OptionalExport = (typeof OPTIONAL_ENDPOINT_EXPORTS)[number];
+export declare function emitHttpApiSource(input: {
+    readonly tree: HttpApiDescriptorTree;
+    readonly targetDirectory: string;
+    readonly importer: string;
+    readonly extractedLiteralsByPath: ReadonlyMap<string, {
+        readonly path: string;
+        readonly method: string;
+        readonly name: string;
+    }>;
+    readonly optionalExportsByPath: ReadonlyMap<string, ReadonlySet<OptionalExport>>;
+    /** When true for an endpoint path, handler returns HttpServerResponse; use handleRaw instead of handle. */
+    readonly handlerIsRawByPath?: ReadonlyMap<string, boolean>;
+}): string;
+export {};
+//# sourceMappingURL=emitHttpApiSource.d.ts.map

package/dist/internal/emitHttpApiSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitHttpApiSource.d.ts","sourceRoot":"","sources":["../../src/internal/emitHttpApiSource.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEV,qBAAqB,EAKtB,MAAM,4BAA4B,CAAC;AAgWpC,QAAA,MAAM,yBAAyB,kDAAmD,CAAC;AACnF,KAAK,cAAc,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAUjE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAC3C,MAAM,EACN;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAC1E,CAAC;IACF,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;IACjF,2GAA2G;IAC3G,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5D,GAAG,MAAM,CA0KT"}