@supacloud/compiler 0.41.0 → 0.42.0

package/dist/analyze.d.ts

@@ -1,7 +1,7 @@
-import type { ApplicationGraph, DependencyGraphCache } from "./types";
+import type { ApplicationGraph, DependencyGraphCache, EffectCompilerOptions } from "./types";
 /**
  * Analyzes source code under rootDir via the native TypeScript Program API.
  * Decorators are matched by name only (Module/Injectable/Inject/Command/Query/Controller/Get/...),
  * without checking import origins, so this package does not need to depend on @supacloud/app.
  */
-export declare function analyzeProject(rootDir: string, include?: string[], cache?: DependencyGraphCache, changedPaths?: string[]): Promise<ApplicationGraph>;
+export declare function analyzeProject(rootDir: string, include?: string[], cache?: DependencyGraphCache, changedPaths?: string[], effectOptions?: EffectCompilerOptions): Promise<ApplicationGraph>;

package/dist/cli.js

@@ -1248,6 +1248,13 @@ var init_validate = __esm(() => {
     "effect-dependencies-required": { code: "SC3038", docsUrl: "https://supacloud.dev/errors/SC3038" },
     "effect-command-retry-forbidden": { code: "SC3039", docsUrl: "https://supacloud.dev/errors/SC3039" },
     "effect-dependency-type": { code: "SC3040", docsUrl: "https://supacloud.dev/errors/SC3040" },
+    "effect-error-type": { code: "SC3041", docsUrl: "https://supacloud.dev/errors/SC3041" },
+    "effect-error-mapping-type": { code: "SC3042", docsUrl: "https://supacloud.dev/errors/SC3042" },
+    "effect-dependency-mismatch": { code: "SC3043", docsUrl: "https://supacloud.dev/errors/SC3043" },
+    "effect-timeout-required": { code: "SC3044", docsUrl: "https://supacloud.dev/errors/SC3044" },
+    "effect-direct-runtime-execution": { code: "SC3045", docsUrl: "https://supacloud.dev/errors/SC3045" },
+    "effect-direct-throw": { code: "SC3046", docsUrl: "https://supacloud.dev/errors/SC3046" },
+    "effect-promise-return": { code: "SC3047", docsUrl: "https://supacloud.dev/errors/SC3047" },
     "invalid-route-response-map": { code: "SC3024", docsUrl: "https://supacloud.dev/errors/SC3024" },
     "invalid-route-response-selector": { code: "SC3025", docsUrl: "https://supacloud.dev/errors/SC3025" },
     "conflicting-route-response-schema": { code: "SC3026", docsUrl: "https://supacloud.dev/errors/SC3026" },
@@ -27815,6 +27822,13 @@ function withDiagnosticMetadata(diagnostic) {
   const metadata = COMPILER_DIAGNOSTIC_CODES[diagnostic.code];
   return metadata ? { ...diagnostic, errorCode: metadata.code, docsUrl: metadata.docsUrl } : diagnostic;
 }
+var DEFAULT_EFFECT_ANALYSIS_OPTIONS = {
+  requireTaggedErrorTypes: true,
+  requireExactDependencyTypes: true,
+  requireTimeoutForDependencies: true,
+  forbidDirectRuntimeExecution: true,
+  forbidDirectThrows: true
+};
 function nodeText(node) {
   return node.getText(node.getSourceFile());
 }
@@ -27860,7 +27874,7 @@ function descendantsOfKind(root, predicate) {
   visit(root);
   return result;
 }
-async function analyzeProject(rootDir, include, cache, changedPaths) {
+async function analyzeProject(rootDir, include, cache, changedPaths, effectOptions = {}) {
   const session = cache?.programSession ?? createIncrementalProgramSession(rootDir);
   if (cache)
     cache.programSession = session;
@@ -27879,8 +27893,21 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
     moduleHandlerFiles: new Map,
     infraResources: new Map,
     infraResourceClasses: new Map,
-    diagnostics: []
+    diagnostics: [],
+    effectOptions: {
+      ...DEFAULT_EFFECT_ANALYSIS_OPTIONS,
+      requireTaggedErrorTypes: effectOptions.requireTaggedErrorTypes ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireTaggedErrorTypes,
+      requireExactDependencyTypes: effectOptions.requireExactDependencyTypes ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireExactDependencyTypes,
+      requireTimeoutForDependencies: effectOptions.requireTimeoutForDependencies ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireTimeoutForDependencies,
+      forbidDirectRuntimeExecution: effectOptions.forbidDirectRuntimeExecution ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.forbidDirectRuntimeExecution,
+      forbidDirectThrows: effectOptions.forbidDirectThrows ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.forbidDirectThrows
+    }
   };
+  if (ctx.effectOptions.forbidDirectRuntimeExecution) {
+    for (const sourceFile of sourceFiles) {
+      scanEffectRuntimeEscapes(sourceFile, ctx);
+    }
+  }
   const nativeTraitFiles = new Map;
   for (const diagnostic of session.getDiagnostics()) {
     ctx.diagnostics.push(toCompilerDiagnostic(diagnostic, rootDir));
@@ -29056,11 +29083,150 @@ function declaredClassType(declaration, ctx) {
   return symbol ? ctx.checker.getDeclaredTypeOfSymbol(symbol) : undefined;
 }
 function typeArgumentsOf(type, ctx) {
-  return isTypeReference(type) ? ctx.checker.getTypeArguments(type) : [];
+  if (!isTypeReference(type))
+    return [];
+  const argumentsFromChecker = ctx.checker.getTypeArguments(type);
+  if (argumentsFromChecker.length > 0)
+    return argumentsFromChecker;
+  const reference = type;
+  if (reference.resolvedTypeArguments && reference.resolvedTypeArguments.length > 0) {
+    return reference.resolvedTypeArguments;
+  }
+  return reference.aliasTypeArguments ?? [];
 }
 function isTypeReference(type) {
   return "target" in type;
 }
+function effectTypeArgumentsOf(type, ctx) {
+  if (!type)
+    return;
+  const reference = isTypeReference(type) ? type : undefined;
+  const target = reference?.target ?? type;
+  const symbol = target.aliasSymbol ?? target.getSymbol();
+  const text = ctx.checker.typeToString(type, undefined, ts7.TypeFormatFlags.NoTruncation);
+  if (symbol?.getName() !== "Effect" && !/^(?:Effect\.)?Effect</.test(text))
+    return;
+  const args = typeArgumentsOf(type, ctx);
+  return args.length >= 3 ? [args[0], args[1], args[2]] : undefined;
+}
+function effectTypeName(type, location, ctx) {
+  return ctx.checker.typeToString(type, location, ts7.TypeFormatFlags.NoTruncation);
+}
+function stringLiteralTypeValue(type) {
+  return (type.flags & ts7.TypeFlags.StringLiteral) !== 0 ? type.value : undefined;
+}
+function effectFailureTags(type, location, ctx) {
+  if ((type.flags & ts7.TypeFlags.Never) !== 0)
+    return { tags: [], invalid: false };
+  if ((type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0) {
+    return { tags: [], invalid: true };
+  }
+  if (type.isUnion()) {
+    return type.types.reduce((result, part) => {
+      const next = effectFailureTags(part, location, ctx);
+      result.tags.push(...next.tags);
+      result.invalid ||= next.invalid;
+      return result;
+    }, { tags: [], invalid: false });
+  }
+  const apparent = ctx.checker.getApparentType(type);
+  for (const propertyName of ["_tag", "tag"]) {
+    const property = ctx.checker.getPropertyOfType(apparent, propertyName);
+    if (!property)
+      continue;
+    const propertyType = ctx.checker.getTypeOfSymbolAtLocation(property, location);
+    const tag = stringLiteralTypeValue(propertyType);
+    if (tag)
+      return { tags: [tag], invalid: false };
+  }
+  return { tags: [], invalid: true };
+}
+function effectEnvironmentNames(type, location, ctx) {
+  if ((type.flags & ts7.TypeFlags.Never) !== 0)
+    return { names: [], invalid: false };
+  if ((type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0) {
+    return { names: [], invalid: true };
+  }
+  if (type.isUnion() || type.isIntersection()) {
+    return type.types.reduce((result, part) => {
+      const next = effectEnvironmentNames(part, location, ctx);
+      result.names.push(...next.names);
+      result.invalid ||= next.invalid;
+      return result;
+    }, { names: [], invalid: false });
+  }
+  const literal = stringLiteralTypeValue(type);
+  if (literal)
+    return { names: [literal], invalid: false };
+  const symbolName = type.getSymbol()?.getName();
+  if (symbolName && symbolName !== "__type" && symbolName !== "__object") {
+    return { names: [symbolName], invalid: false };
+  }
+  const text = effectTypeName(type, location, ctx).trim();
+  if (text && text !== "object")
+    return { names: [text], invalid: false };
+  return { names: [], invalid: true };
+}
+function sortedUnique(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right, "en"));
+}
+function pushEffectDiagnostic(ctx, code, file, line, message, suggestion) {
+  const metadata = COMPILER_DIAGNOSTIC_CODES[code];
+  ctx.diagnostics.push({
+    severity: "error",
+    code,
+    ...metadata ? { errorCode: metadata.code, docsUrl: metadata.docsUrl } : {},
+    file,
+    line,
+    message,
+    suggestion
+  });
+}
+function scanEffectRuntimeEscapes(sourceFile, ctx) {
+  const relativeFile = sourcePath(ctx.rootDir, sourceFile.fileName);
+  if (/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(relativeFile))
+    return;
+  const namespaceBindings = new Set;
+  const runtimeBindings = new Set;
+  for (const statement of sourceFile.statements) {
+    if (!ts7.isImportDeclaration(statement) || !ts7.isStringLiteral(statement.moduleSpecifier))
+      continue;
+    const moduleName = statement.moduleSpecifier.text;
+    if (moduleName !== "effect" && moduleName !== "effect/Effect" && moduleName !== "effect/Runtime")
+      continue;
+    const clause = statement.importClause;
+    if (!clause)
+      continue;
+    if (clause.name)
+      namespaceBindings.add(clause.name.text);
+    if (clause.namedBindings && ts7.isNamespaceImport(clause.namedBindings)) {
+      namespaceBindings.add(clause.namedBindings.name.text);
+    } else if (clause.namedBindings && ts7.isNamedImports(clause.namedBindings)) {
+      for (const element of clause.namedBindings.elements) {
+        const imported = element.propertyName?.text ?? element.name.text;
+        if (moduleName === "effect" && (imported === "Effect" || imported === "Runtime")) {
+          namespaceBindings.add(element.name.text);
+        }
+        if (["runPromise", "runPromiseExit", "runSync", "runFork"].includes(imported)) {
+          runtimeBindings.add(element.name.text);
+        }
+      }
+    }
+  }
+  if (namespaceBindings.size === 0 && runtimeBindings.size === 0)
+    return;
+  for (const call of descendantsOfKind(sourceFile, ts7.isCallExpression)) {
+    let runtimeName;
+    if (ts7.isPropertyAccessExpression(call.expression) && namespaceBindings.has(call.expression.expression.getText(sourceFile)) && ["runPromise", "runPromiseExit", "runSync", "runFork"].includes(call.expression.name.text)) {
+      runtimeName = call.expression.name.text;
+    } else if (ts7.isIdentifier(call.expression) && runtimeBindings.has(call.expression.text)) {
+      runtimeName = call.expression.text;
+    }
+    if (!runtimeName)
+      continue;
+    pushEffectDiagnostic(ctx, "effect-direct-runtime-execution", sourcePath(ctx.rootDir, sourceFile.fileName), lineOf(call), `Direct ${runtimeName} execution escapes the Effect boundary.`, "Return the Effect program to the Elysia boundary; only the framework adapter may interpret it.");
+  }
+}
 function isUnknownOrAny(type) {
   return (type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0;
 }
@@ -29124,7 +29290,8 @@ function parseController(input, ctx) {
         handler: propertyName(method.name)
       };
       const signature = ctx.checker.getSignatureFromDeclaration(method);
-      const resultType = signature && ctx.checker.typeToString(signature.getReturnType());
+      const returnType = signature?.getReturnType();
+      const resultType = returnType && ctx.checker.typeToString(returnType);
       if (resultType && /\bResponse\b/.test(resultType))
         route.nativeResponse = true;
       const pathParams = [];
@@ -29455,6 +29622,18 @@ function parseController(input, ctx) {
                 });
               } else {
                 effect.dependencies = dependenciesExpr.elements.map((element) => element.text);
+                if (new Set(effect.dependencies).size !== effect.dependencies.length) {
+                  ctx.diagnostics.push({
+                    severity: "error",
+                    code: "invalid-effect-dependencies",
+                    errorCode: "SC3033",
+                    docsUrl: "https://supacloud.dev/errors/SC3033",
+                    file,
+                    line: lineOf(dependenciesExpr),
+                    message: `Route ${route.handler} effect.dependencies must not contain duplicate service names.`,
+                    suggestion: "List each logical Effect dependency exactly once."
+                  });
+                }
               }
             }
             const errorsExpr = getProp(effectObject, "errors");
@@ -29503,10 +29682,26 @@ function parseController(input, ctx) {
                   errors.push({ tag, code, status, ...message === undefined ? {} : { message } });
                 }
                 effect.errors = errors;
+                if (new Set(errors.map((entry) => entry.tag)).size !== errors.length) {
+                  ctx.diagnostics.push({
+                    severity: "error",
+                    code: "invalid-effect-errors",
+                    errorCode: "SC3034",
+                    docsUrl: "https://supacloud.dev/errors/SC3034",
+                    file,
+                    line: lineOf(errorsExpr),
+                    message: `Route ${route.handler} effect.errors must not contain duplicate tags.`,
+                    suggestion: "Map each tagged failure exactly once."
+                  });
+                }
               }
             }
             route.effect = effect;
-            if (!resultType || !/\bEffect(?:\.Effect)?(?:<|\s)/.test(resultType)) {
+            const effectArguments = effectTypeArgumentsOf(returnType, ctx);
+            const promiseReturn = Boolean(resultType && /\bPromise(?:<|\s)/.test(resultType));
+            if (promiseReturn) {
+              pushEffectDiagnostic(ctx, "effect-promise-return", file, lineOf(method), `Route ${route.handler} returns Promise instead of an Effect program.`, "Return Effect.Effect<Success, Failure, Requirements>; the Elysia boundary owns Promise interpretation.");
+            } else if (!effectArguments) {
               ctx.diagnostics.push({
                 severity: "error",
                 code: "effect-return-type",
@@ -29518,18 +29713,37 @@ function parseController(input, ctx) {
                 suggestion: "Return Effect.Effect<Success, Failure, Requirements> from the handler."
               });
             }
-            for (const dependency of effect.dependencies ?? []) {
-              if (!resultType?.includes(dependency)) {
-                ctx.diagnostics.push({
-                  severity: "error",
-                  code: "effect-dependency-type",
-                  errorCode: "SC3040",
-                  docsUrl: "https://supacloud.dev/errors/SC3040",
-                  file,
-                  line: lineOf(method),
-                  message: `Route ${route.handler} declares Effect dependency "${dependency}", but it is absent from the return type environment ${resultType ?? "unknown"}.`,
-                  suggestion: "Keep effect.dependencies aligned with the third Effect type parameter."
-                });
+            if (effectArguments) {
+              const [, failureType, environmentType] = effectArguments;
+              const failure = effectFailureTags(failureType, method, ctx);
+              if (ctx.effectOptions.requireTaggedErrorTypes && failure.invalid) {
+                pushEffectDiagnostic(ctx, "effect-error-type", file, lineOf(method), `Route ${route.handler} must use never or a tagged failure union in Effect's error channel, not ${effectTypeName(failureType, method, ctx)}.`, "Replace unknown/any with never or a union of objects carrying a literal _tag.");
+              } else if (ctx.effectOptions.requireTaggedErrorTypes && effect.errors !== undefined && !failure.invalid) {
+                const declaredTags = sortedUnique(effect.errors.map((entry) => entry.tag));
+                const typedTags = sortedUnique(failure.tags);
+                if (declaredTags.join("\x00") !== typedTags.join("\x00")) {
+                  pushEffectDiagnostic(ctx, "effect-error-mapping-type", file, lineOf(method), `Route ${route.handler} maps [${declaredTags.join(", ")}], but its Effect failure type declares [${typedTags.join(", ")}].`, "Make effect.errors and the Effect error type the same tagged union; do not hide unmapped failures.");
+                }
+              }
+              const environment = effectEnvironmentNames(environmentType, method, ctx);
+              if (ctx.effectOptions.requireExactDependencyTypes && effect.dependencies !== undefined) {
+                if (environment.invalid) {
+                  pushEffectDiagnostic(ctx, "effect-dependency-mismatch", file, lineOf(method), `Route ${route.handler} uses an Effect environment that cannot be represented by its explicit dependency list.`, "Use named service types or never in the third Effect type parameter.");
+                } else {
+                  const declaredDependencies = sortedUnique(effect.dependencies);
+                  const typedDependencies = sortedUnique(environment.names);
+                  if (declaredDependencies.join("\x00") !== typedDependencies.join("\x00")) {
+                    pushEffectDiagnostic(ctx, "effect-dependency-mismatch", file, lineOf(method), `Route ${route.handler} declares dependencies [${declaredDependencies.join(", ")}], but its Effect environment is [${typedDependencies.join(", ")}].`, "Make effect.dependencies exactly match the third Effect type parameter.");
+                  }
+                }
+              }
+              if (ctx.effectOptions.requireTimeoutForDependencies && (effect.dependencies?.length ?? 0) > 0 && effect.timeoutMs === undefined) {
+                pushEffectDiagnostic(ctx, "effect-timeout-required", file, lineOf(method), `Route ${route.handler} declares external Effect dependencies without a timeout.`, "Add a positive effect.timeoutMs so external I/O cannot occupy a request indefinitely.");
+              }
+            }
+            if (ctx.effectOptions.forbidDirectThrows && method.body) {
+              for (const throwStatement of descendantsOfKind(method.body, ts7.isThrowStatement)) {
+                pushEffectDiagnostic(ctx, "effect-direct-throw", file, lineOf(throwStatement), `Route ${route.handler} throws directly instead of representing failure in Effect.`, "Use Effect.fail with a tagged error value and map it in effect.errors.");
               }
             }
           }
@@ -30851,7 +31065,7 @@ async function renderOptionalGraphql(options) {
 }
 async function compileProject(options) {
   options = withDefaultGovernance(options);
-  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths, options.effect);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
@@ -30916,7 +31130,7 @@ async function compileProject(options) {
 }
 async function checkProject(options) {
   options = withDefaultGovernance(options);
-  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths, options.effect);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
@@ -31404,6 +31618,7 @@ function optionsKeyOf(options) {
     openApi: options.openApi,
     generatePermissions: options.generatePermissions,
     typeSafety: options.typeSafety,
+    effect: options.effect,
     treeShakeUnusedProviders: options.treeShakeUnusedProviders,
     graphql: options.graphql
   });
@@ -31735,7 +31950,12 @@ var DEFAULT_SUPACLOUD_CONFIG = {
   effect: {
     requireRouteEffects: true,
     requireErrorMappings: true,
-    requireDependencies: true
+    requireDependencies: true,
+    requireTaggedErrorTypes: true,
+    requireExactDependencyTypes: true,
+    requireTimeoutForDependencies: true,
+    forbidDirectRuntimeExecution: true,
+    forbidDirectThrows: true
   }
 };
 function defineSupacloudConfig(config = {}) {
@@ -31807,10 +32027,28 @@ function validateGovernanceConfig(config) {
       throw new Error(`${key} must be a boolean.`);
   }
   if (config.effect !== undefined) {
-    if (!isRecord(config.effect) || Object.keys(config.effect).some((key) => !["requireRouteEffects", "requireErrorMappings", "requireDependencies"].includes(key))) {
-      throw new Error("effect accepts requireRouteEffects, requireErrorMappings and requireDependencies.");
-    }
-    for (const key of ["requireRouteEffects", "requireErrorMappings", "requireDependencies"]) {
+    if (!isRecord(config.effect) || Object.keys(config.effect).some((key) => ![
+      "requireRouteEffects",
+      "requireErrorMappings",
+      "requireDependencies",
+      "requireTaggedErrorTypes",
+      "requireExactDependencyTypes",
+      "requireTimeoutForDependencies",
+      "forbidDirectRuntimeExecution",
+      "forbidDirectThrows"
+    ].includes(key))) {
+      throw new Error("effect contains an unsupported governance option.");
+    }
+    for (const key of [
+      "requireRouteEffects",
+      "requireErrorMappings",
+      "requireDependencies",
+      "requireTaggedErrorTypes",
+      "requireExactDependencyTypes",
+      "requireTimeoutForDependencies",
+      "forbidDirectRuntimeExecution",
+      "forbidDirectThrows"
+    ]) {
       if (config.effect[key] !== undefined && typeof config.effect[key] !== "boolean") {
         throw new Error(`effect.${key} must be boolean.`);
       }
@@ -33124,7 +33362,7 @@ import { resolve as resolve18 } from "node:path";
 var MIGRATION_APP_VERSION = "0.24.0";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.28.0";
+var MIGRATION_ELYSIA_VERSION = "0.29.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;

package/dist/index.js

@@ -1247,6 +1247,13 @@ var init_validate = __esm(() => {
     "effect-dependencies-required": { code: "SC3038", docsUrl: "https://supacloud.dev/errors/SC3038" },
     "effect-command-retry-forbidden": { code: "SC3039", docsUrl: "https://supacloud.dev/errors/SC3039" },
     "effect-dependency-type": { code: "SC3040", docsUrl: "https://supacloud.dev/errors/SC3040" },
+    "effect-error-type": { code: "SC3041", docsUrl: "https://supacloud.dev/errors/SC3041" },
+    "effect-error-mapping-type": { code: "SC3042", docsUrl: "https://supacloud.dev/errors/SC3042" },
+    "effect-dependency-mismatch": { code: "SC3043", docsUrl: "https://supacloud.dev/errors/SC3043" },
+    "effect-timeout-required": { code: "SC3044", docsUrl: "https://supacloud.dev/errors/SC3044" },
+    "effect-direct-runtime-execution": { code: "SC3045", docsUrl: "https://supacloud.dev/errors/SC3045" },
+    "effect-direct-throw": { code: "SC3046", docsUrl: "https://supacloud.dev/errors/SC3046" },
+    "effect-promise-return": { code: "SC3047", docsUrl: "https://supacloud.dev/errors/SC3047" },
     "invalid-route-response-map": { code: "SC3024", docsUrl: "https://supacloud.dev/errors/SC3024" },
     "invalid-route-response-selector": { code: "SC3025", docsUrl: "https://supacloud.dev/errors/SC3025" },
     "conflicting-route-response-schema": { code: "SC3026", docsUrl: "https://supacloud.dev/errors/SC3026" },
@@ -27774,6 +27781,13 @@ function withDiagnosticMetadata(diagnostic) {
   const metadata = COMPILER_DIAGNOSTIC_CODES[diagnostic.code];
   return metadata ? { ...diagnostic, errorCode: metadata.code, docsUrl: metadata.docsUrl } : diagnostic;
 }
+var DEFAULT_EFFECT_ANALYSIS_OPTIONS = {
+  requireTaggedErrorTypes: true,
+  requireExactDependencyTypes: true,
+  requireTimeoutForDependencies: true,
+  forbidDirectRuntimeExecution: true,
+  forbidDirectThrows: true
+};
 function nodeText(node) {
   return node.getText(node.getSourceFile());
 }
@@ -27819,7 +27833,7 @@ function descendantsOfKind(root, predicate) {
   visit(root);
   return result;
 }
-async function analyzeProject(rootDir, include, cache, changedPaths) {
+async function analyzeProject(rootDir, include, cache, changedPaths, effectOptions = {}) {
   const session = cache?.programSession ?? createIncrementalProgramSession(rootDir);
   if (cache)
     cache.programSession = session;
@@ -27838,8 +27852,21 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
     moduleHandlerFiles: new Map,
     infraResources: new Map,
     infraResourceClasses: new Map,
-    diagnostics: []
+    diagnostics: [],
+    effectOptions: {
+      ...DEFAULT_EFFECT_ANALYSIS_OPTIONS,
+      requireTaggedErrorTypes: effectOptions.requireTaggedErrorTypes ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireTaggedErrorTypes,
+      requireExactDependencyTypes: effectOptions.requireExactDependencyTypes ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireExactDependencyTypes,
+      requireTimeoutForDependencies: effectOptions.requireTimeoutForDependencies ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireTimeoutForDependencies,
+      forbidDirectRuntimeExecution: effectOptions.forbidDirectRuntimeExecution ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.forbidDirectRuntimeExecution,
+      forbidDirectThrows: effectOptions.forbidDirectThrows ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.forbidDirectThrows
+    }
   };
+  if (ctx.effectOptions.forbidDirectRuntimeExecution) {
+    for (const sourceFile of sourceFiles) {
+      scanEffectRuntimeEscapes(sourceFile, ctx);
+    }
+  }
   const nativeTraitFiles = new Map;
   for (const diagnostic of session.getDiagnostics()) {
     ctx.diagnostics.push(toCompilerDiagnostic(diagnostic, rootDir));
@@ -29015,11 +29042,150 @@ function declaredClassType(declaration, ctx) {
   return symbol ? ctx.checker.getDeclaredTypeOfSymbol(symbol) : undefined;
 }
 function typeArgumentsOf(type, ctx) {
-  return isTypeReference(type) ? ctx.checker.getTypeArguments(type) : [];
+  if (!isTypeReference(type))
+    return [];
+  const argumentsFromChecker = ctx.checker.getTypeArguments(type);
+  if (argumentsFromChecker.length > 0)
+    return argumentsFromChecker;
+  const reference = type;
+  if (reference.resolvedTypeArguments && reference.resolvedTypeArguments.length > 0) {
+    return reference.resolvedTypeArguments;
+  }
+  return reference.aliasTypeArguments ?? [];
 }
 function isTypeReference(type) {
   return "target" in type;
 }
+function effectTypeArgumentsOf(type, ctx) {
+  if (!type)
+    return;
+  const reference = isTypeReference(type) ? type : undefined;
+  const target = reference?.target ?? type;
+  const symbol = target.aliasSymbol ?? target.getSymbol();
+  const text = ctx.checker.typeToString(type, undefined, ts7.TypeFormatFlags.NoTruncation);
+  if (symbol?.getName() !== "Effect" && !/^(?:Effect\.)?Effect</.test(text))
+    return;
+  const args = typeArgumentsOf(type, ctx);
+  return args.length >= 3 ? [args[0], args[1], args[2]] : undefined;
+}
+function effectTypeName(type, location, ctx) {
+  return ctx.checker.typeToString(type, location, ts7.TypeFormatFlags.NoTruncation);
+}
+function stringLiteralTypeValue(type) {
+  return (type.flags & ts7.TypeFlags.StringLiteral) !== 0 ? type.value : undefined;
+}
+function effectFailureTags(type, location, ctx) {
+  if ((type.flags & ts7.TypeFlags.Never) !== 0)
+    return { tags: [], invalid: false };
+  if ((type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0) {
+    return { tags: [], invalid: true };
+  }
+  if (type.isUnion()) {
+    return type.types.reduce((result, part) => {
+      const next = effectFailureTags(part, location, ctx);
+      result.tags.push(...next.tags);
+      result.invalid ||= next.invalid;
+      return result;
+    }, { tags: [], invalid: false });
+  }
+  const apparent = ctx.checker.getApparentType(type);
+  for (const propertyName of ["_tag", "tag"]) {
+    const property = ctx.checker.getPropertyOfType(apparent, propertyName);
+    if (!property)
+      continue;
+    const propertyType = ctx.checker.getTypeOfSymbolAtLocation(property, location);
+    const tag = stringLiteralTypeValue(propertyType);
+    if (tag)
+      return { tags: [tag], invalid: false };
+  }
+  return { tags: [], invalid: true };
+}
+function effectEnvironmentNames(type, location, ctx) {
+  if ((type.flags & ts7.TypeFlags.Never) !== 0)
+    return { names: [], invalid: false };
+  if ((type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0) {
+    return { names: [], invalid: true };
+  }
+  if (type.isUnion() || type.isIntersection()) {
+    return type.types.reduce((result, part) => {
+      const next = effectEnvironmentNames(part, location, ctx);
+      result.names.push(...next.names);
+      result.invalid ||= next.invalid;
+      return result;
+    }, { names: [], invalid: false });
+  }
+  const literal = stringLiteralTypeValue(type);
+  if (literal)
+    return { names: [literal], invalid: false };
+  const symbolName = type.getSymbol()?.getName();
+  if (symbolName && symbolName !== "__type" && symbolName !== "__object") {
+    return { names: [symbolName], invalid: false };
+  }
+  const text = effectTypeName(type, location, ctx).trim();
+  if (text && text !== "object")
+    return { names: [text], invalid: false };
+  return { names: [], invalid: true };
+}
+function sortedUnique(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right, "en"));
+}
+function pushEffectDiagnostic(ctx, code, file, line, message, suggestion) {
+  const metadata = COMPILER_DIAGNOSTIC_CODES[code];
+  ctx.diagnostics.push({
+    severity: "error",
+    code,
+    ...metadata ? { errorCode: metadata.code, docsUrl: metadata.docsUrl } : {},
+    file,
+    line,
+    message,
+    suggestion
+  });
+}
+function scanEffectRuntimeEscapes(sourceFile, ctx) {
+  const relativeFile = sourcePath(ctx.rootDir, sourceFile.fileName);
+  if (/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(relativeFile))
+    return;
+  const namespaceBindings = new Set;
+  const runtimeBindings = new Set;
+  for (const statement of sourceFile.statements) {
+    if (!ts7.isImportDeclaration(statement) || !ts7.isStringLiteral(statement.moduleSpecifier))
+      continue;
+    const moduleName = statement.moduleSpecifier.text;
+    if (moduleName !== "effect" && moduleName !== "effect/Effect" && moduleName !== "effect/Runtime")
+      continue;
+    const clause = statement.importClause;
+    if (!clause)
+      continue;
+    if (clause.name)
+      namespaceBindings.add(clause.name.text);
+    if (clause.namedBindings && ts7.isNamespaceImport(clause.namedBindings)) {
+      namespaceBindings.add(clause.namedBindings.name.text);
+    } else if (clause.namedBindings && ts7.isNamedImports(clause.namedBindings)) {
+      for (const element of clause.namedBindings.elements) {
+        const imported = element.propertyName?.text ?? element.name.text;
+        if (moduleName === "effect" && (imported === "Effect" || imported === "Runtime")) {
+          namespaceBindings.add(element.name.text);
+        }
+        if (["runPromise", "runPromiseExit", "runSync", "runFork"].includes(imported)) {
+          runtimeBindings.add(element.name.text);
+        }
+      }
+    }
+  }
+  if (namespaceBindings.size === 0 && runtimeBindings.size === 0)
+    return;
+  for (const call of descendantsOfKind(sourceFile, ts7.isCallExpression)) {
+    let runtimeName;
+    if (ts7.isPropertyAccessExpression(call.expression) && namespaceBindings.has(call.expression.expression.getText(sourceFile)) && ["runPromise", "runPromiseExit", "runSync", "runFork"].includes(call.expression.name.text)) {
+      runtimeName = call.expression.name.text;
+    } else if (ts7.isIdentifier(call.expression) && runtimeBindings.has(call.expression.text)) {
+      runtimeName = call.expression.text;
+    }
+    if (!runtimeName)
+      continue;
+    pushEffectDiagnostic(ctx, "effect-direct-runtime-execution", sourcePath(ctx.rootDir, sourceFile.fileName), lineOf(call), `Direct ${runtimeName} execution escapes the Effect boundary.`, "Return the Effect program to the Elysia boundary; only the framework adapter may interpret it.");
+  }
+}
 function isUnknownOrAny(type) {
   return (type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0;
 }
@@ -29083,7 +29249,8 @@ function parseController(input, ctx) {
         handler: propertyName(method.name)
       };
       const signature = ctx.checker.getSignatureFromDeclaration(method);
-      const resultType = signature && ctx.checker.typeToString(signature.getReturnType());
+      const returnType = signature?.getReturnType();
+      const resultType = returnType && ctx.checker.typeToString(returnType);
       if (resultType && /\bResponse\b/.test(resultType))
         route.nativeResponse = true;
       const pathParams = [];
@@ -29414,6 +29581,18 @@ function parseController(input, ctx) {
                 });
               } else {
                 effect.dependencies = dependenciesExpr.elements.map((element) => element.text);
+                if (new Set(effect.dependencies).size !== effect.dependencies.length) {
+                  ctx.diagnostics.push({
+                    severity: "error",
+                    code: "invalid-effect-dependencies",
+                    errorCode: "SC3033",
+                    docsUrl: "https://supacloud.dev/errors/SC3033",
+                    file,
+                    line: lineOf(dependenciesExpr),
+                    message: `Route ${route.handler} effect.dependencies must not contain duplicate service names.`,
+                    suggestion: "List each logical Effect dependency exactly once."
+                  });
+                }
               }
             }
             const errorsExpr = getProp(effectObject, "errors");
@@ -29462,10 +29641,26 @@ function parseController(input, ctx) {
                   errors.push({ tag, code, status, ...message === undefined ? {} : { message } });
                 }
                 effect.errors = errors;
+                if (new Set(errors.map((entry) => entry.tag)).size !== errors.length) {
+                  ctx.diagnostics.push({
+                    severity: "error",
+                    code: "invalid-effect-errors",
+                    errorCode: "SC3034",
+                    docsUrl: "https://supacloud.dev/errors/SC3034",
+                    file,
+                    line: lineOf(errorsExpr),
+                    message: `Route ${route.handler} effect.errors must not contain duplicate tags.`,
+                    suggestion: "Map each tagged failure exactly once."
+                  });
+                }
               }
             }
             route.effect = effect;
-            if (!resultType || !/\bEffect(?:\.Effect)?(?:<|\s)/.test(resultType)) {
+            const effectArguments = effectTypeArgumentsOf(returnType, ctx);
+            const promiseReturn = Boolean(resultType && /\bPromise(?:<|\s)/.test(resultType));
+            if (promiseReturn) {
+              pushEffectDiagnostic(ctx, "effect-promise-return", file, lineOf(method), `Route ${route.handler} returns Promise instead of an Effect program.`, "Return Effect.Effect<Success, Failure, Requirements>; the Elysia boundary owns Promise interpretation.");
+            } else if (!effectArguments) {
               ctx.diagnostics.push({
                 severity: "error",
                 code: "effect-return-type",
@@ -29477,18 +29672,37 @@ function parseController(input, ctx) {
                 suggestion: "Return Effect.Effect<Success, Failure, Requirements> from the handler."
               });
             }
-            for (const dependency of effect.dependencies ?? []) {
-              if (!resultType?.includes(dependency)) {
-                ctx.diagnostics.push({
-                  severity: "error",
-                  code: "effect-dependency-type",
-                  errorCode: "SC3040",
-                  docsUrl: "https://supacloud.dev/errors/SC3040",
-                  file,
-                  line: lineOf(method),
-                  message: `Route ${route.handler} declares Effect dependency "${dependency}", but it is absent from the return type environment ${resultType ?? "unknown"}.`,
-                  suggestion: "Keep effect.dependencies aligned with the third Effect type parameter."
-                });
+            if (effectArguments) {
+              const [, failureType, environmentType] = effectArguments;
+              const failure = effectFailureTags(failureType, method, ctx);
+              if (ctx.effectOptions.requireTaggedErrorTypes && failure.invalid) {
+                pushEffectDiagnostic(ctx, "effect-error-type", file, lineOf(method), `Route ${route.handler} must use never or a tagged failure union in Effect's error channel, not ${effectTypeName(failureType, method, ctx)}.`, "Replace unknown/any with never or a union of objects carrying a literal _tag.");
+              } else if (ctx.effectOptions.requireTaggedErrorTypes && effect.errors !== undefined && !failure.invalid) {
+                const declaredTags = sortedUnique(effect.errors.map((entry) => entry.tag));
+                const typedTags = sortedUnique(failure.tags);
+                if (declaredTags.join("\x00") !== typedTags.join("\x00")) {
+                  pushEffectDiagnostic(ctx, "effect-error-mapping-type", file, lineOf(method), `Route ${route.handler} maps [${declaredTags.join(", ")}], but its Effect failure type declares [${typedTags.join(", ")}].`, "Make effect.errors and the Effect error type the same tagged union; do not hide unmapped failures.");
+                }
+              }
+              const environment = effectEnvironmentNames(environmentType, method, ctx);
+              if (ctx.effectOptions.requireExactDependencyTypes && effect.dependencies !== undefined) {
+                if (environment.invalid) {
+                  pushEffectDiagnostic(ctx, "effect-dependency-mismatch", file, lineOf(method), `Route ${route.handler} uses an Effect environment that cannot be represented by its explicit dependency list.`, "Use named service types or never in the third Effect type parameter.");
+                } else {
+                  const declaredDependencies = sortedUnique(effect.dependencies);
+                  const typedDependencies = sortedUnique(environment.names);
+                  if (declaredDependencies.join("\x00") !== typedDependencies.join("\x00")) {
+                    pushEffectDiagnostic(ctx, "effect-dependency-mismatch", file, lineOf(method), `Route ${route.handler} declares dependencies [${declaredDependencies.join(", ")}], but its Effect environment is [${typedDependencies.join(", ")}].`, "Make effect.dependencies exactly match the third Effect type parameter.");
+                  }
+                }
+              }
+              if (ctx.effectOptions.requireTimeoutForDependencies && (effect.dependencies?.length ?? 0) > 0 && effect.timeoutMs === undefined) {
+                pushEffectDiagnostic(ctx, "effect-timeout-required", file, lineOf(method), `Route ${route.handler} declares external Effect dependencies without a timeout.`, "Add a positive effect.timeoutMs so external I/O cannot occupy a request indefinitely.");
+              }
+            }
+            if (ctx.effectOptions.forbidDirectThrows && method.body) {
+              for (const throwStatement of descendantsOfKind(method.body, ts7.isThrowStatement)) {
+                pushEffectDiagnostic(ctx, "effect-direct-throw", file, lineOf(throwStatement), `Route ${route.handler} throws directly instead of representing failure in Effect.`, "Use Effect.fail with a tagged error value and map it in effect.errors.");
               }
             }
           }
@@ -30812,7 +31026,7 @@ async function renderOptionalGraphql(options) {
 }
 async function compileProject(options) {
   options = withDefaultGovernance(options);
-  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths, options.effect);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
@@ -30877,7 +31091,7 @@ async function compileProject(options) {
 }
 async function checkProject(options) {
   options = withDefaultGovernance(options);
-  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths, options.effect);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
@@ -32528,6 +32742,7 @@ function optionsKeyOf(options) {
     openApi: options.openApi,
     generatePermissions: options.generatePermissions,
     typeSafety: options.typeSafety,
+    effect: options.effect,
     treeShakeUnusedProviders: options.treeShakeUnusedProviders,
     graphql: options.graphql
   });
@@ -32840,7 +33055,7 @@ import { resolve as resolve17 } from "node:path";
 var MIGRATION_APP_VERSION = "0.24.0";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.28.0";
+var MIGRATION_ELYSIA_VERSION = "0.29.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;
@@ -34014,7 +34229,12 @@ var DEFAULT_SUPACLOUD_CONFIG = {
   effect: {
     requireRouteEffects: true,
     requireErrorMappings: true,
-    requireDependencies: true
+    requireDependencies: true,
+    requireTaggedErrorTypes: true,
+    requireExactDependencyTypes: true,
+    requireTimeoutForDependencies: true,
+    forbidDirectRuntimeExecution: true,
+    forbidDirectThrows: true
   }
 };
 function defineSupacloudConfig(config = {}) {
@@ -34086,10 +34306,28 @@ function validateGovernanceConfig(config) {
       throw new Error(`${key} must be a boolean.`);
   }
   if (config.effect !== undefined) {
-    if (!isRecord(config.effect) || Object.keys(config.effect).some((key) => !["requireRouteEffects", "requireErrorMappings", "requireDependencies"].includes(key))) {
-      throw new Error("effect accepts requireRouteEffects, requireErrorMappings and requireDependencies.");
-    }
-    for (const key of ["requireRouteEffects", "requireErrorMappings", "requireDependencies"]) {
+    if (!isRecord(config.effect) || Object.keys(config.effect).some((key) => ![
+      "requireRouteEffects",
+      "requireErrorMappings",
+      "requireDependencies",
+      "requireTaggedErrorTypes",
+      "requireExactDependencyTypes",
+      "requireTimeoutForDependencies",
+      "forbidDirectRuntimeExecution",
+      "forbidDirectThrows"
+    ].includes(key))) {
+      throw new Error("effect contains an unsupported governance option.");
+    }
+    for (const key of [
+      "requireRouteEffects",
+      "requireErrorMappings",
+      "requireDependencies",
+      "requireTaggedErrorTypes",
+      "requireExactDependencyTypes",
+      "requireTimeoutForDependencies",
+      "forbidDirectRuntimeExecution",
+      "forbidDirectThrows"
+    ]) {
       if (config.effect[key] !== undefined && typeof config.effect[key] !== "boolean") {
         throw new Error(`effect.${key} must be boolean.`);
       }

package/dist/migration-elysia-version.d.ts

@@ -1 +1 @@
-export declare const MIGRATION_ELYSIA_VERSION = "0.28.0";
+export declare const MIGRATION_ELYSIA_VERSION = "0.29.0";

package/dist/types.d.ts

@@ -456,6 +456,16 @@ export interface EffectCompilerOptions {
     requireErrorMappings?: boolean;
     /** Require an explicit dependency list for Effect environments. */
     requireDependencies?: boolean;
+    /** Reject unknown/any failures and require a tagged failure union. */
+    requireTaggedErrorTypes?: boolean;
+    /** Require effect.dependencies to exactly match the Effect environment type. */
+    requireExactDependencyTypes?: boolean;
+    /** Require a timeout whenever the route declares Effect dependencies. */
+    requireTimeoutForDependencies?: boolean;
+    /** Reject direct Effect.run* calls inside governed route handlers. */
+    forbidDirectRuntimeExecution?: boolean;
+    /** Reject direct throw statements inside governed route handlers. */
+    forbidDirectThrows?: boolean;
 }
 export interface GraphqlOptions {
     /** Additionally emit standard TypedDocumentNode artifacts for GraphQL ecosystem clients. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Static compiler for @supacloud/app metadata: builds the application graph from AST, validates it, and generates reflection-free factory code",
   "type": "module",
   "main": "./dist/index.js",