@clayroach/effect-unplugin 4.0.0-source-tracing.0

package/src/annotateEffects.ts

@@ -0,0 +1,201 @@
+/**
+ * Effect tree-shaking annotations transformer.
+ *
+ * Adds `\/* @__PURE__ *\/` comments to Effect calls for bundler tree-shaking.
+ *
+ * @since 0.0.1
+ */
+import { parse } from "@babel/parser"
+import * as _traverse from "@babel/traverse"
+import * as _generate from "@babel/generator"
+import * as t from "@babel/types"
+
+type NodePath<T = t.Node> = _traverse.NodePath<T>
+
+type GenerateFn = (
+  ast: t.Node,
+  opts: _generate.GeneratorOptions,
+  code?: string | { [filename: string]: string }
+) => _generate.GeneratorResult
+
+// Handle CommonJS default exports - runtime interop
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const traverse: (ast: t.Node, opts: _traverse.TraverseOptions) => void = (_traverse as any).default ?? _traverse
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const generate: GenerateFn = (_generate as any).default ?? _generate
+
+/**
+ * Effect module names that should have pure annotations.
+ */
+const EFFECT_MODULES = new Set([
+  "Effect",
+  "Option",
+  "Either",
+  "Data",
+  "Schema",
+  "Array",
+  "Chunk",
+  "HashMap",
+  "HashSet",
+  "List",
+  "Queue",
+  "Stream",
+  "Layer",
+  "Scope",
+  "Ref",
+  "SynchronizedRef",
+  "SubscriptionRef",
+  "Duration",
+  "Schedule",
+  "Cause",
+  "Exit",
+  "Match",
+  "Boolean",
+  "Number",
+  "String",
+  "Struct",
+  "Tuple",
+  "Function",
+  "Predicate",
+  "Order",
+  "Equivalence",
+  "Context",
+  "Brand",
+  "Types"
+])
+
+/**
+ * @since 0.0.1
+ * @category models
+ */
+export interface AnnotateResult {
+  readonly code: string
+  readonly map?: unknown
+  readonly transformed: boolean
+}
+
+/**
+ * Checks if a call expression already has a pure annotation.
+ */
+function hasPureAnnotation(node: t.CallExpression): boolean {
+  const comments = node.leadingComments
+  if (!comments) return false
+  return comments.some(
+    (comment) =>
+      comment.type === "CommentBlock" &&
+      (comment.value.includes("@__PURE__") || comment.value.includes("#__PURE__"))
+  )
+}
+
+/**
+ * Checks if a call is to an Effect module method.
+ */
+function isEffectModuleCall(node: t.CallExpression): boolean {
+  const callee = node.callee
+
+  // Effect.succeed(...) or Option.some(...)
+  if (
+    t.isMemberExpression(callee) &&
+    t.isIdentifier(callee.object) &&
+    EFFECT_MODULES.has(callee.object.name)
+  ) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Checks if a CallExpression is in a context where pure annotation is useful.
+ * Only annotate calls in variable declarations or export declarations.
+ */
+function isInAnnotatableContext(path: NodePath<t.CallExpression>): boolean {
+  let parent: NodePath | null = path.parentPath
+
+  while (parent !== null) {
+    const node = parent.node
+
+    // Variable declaration: const x = Effect.succeed(...)
+    if (t.isVariableDeclarator(node)) {
+      return true
+    }
+
+    // Export: export const x = Effect.succeed(...)
+    if (t.isExportDefaultDeclaration(node) || t.isExportNamedDeclaration(node)) {
+      return true
+    }
+
+    // Return statement: return Effect.succeed(...)
+    if (t.isReturnStatement(node)) {
+      return true
+    }
+
+    // Arrow function body: () => Effect.succeed(...)
+    if (t.isArrowFunctionExpression(node)) {
+      return true
+    }
+
+    // Stop at block statements
+    if (t.isBlockStatement(node) || t.isProgram(node)) {
+      break
+    }
+
+    parent = parent.parentPath
+  }
+
+  return false
+}
+
+/**
+ * Transforms source code to add pure annotations to Effect calls.
+ *
+ * @since 0.0.1
+ * @category transform
+ */
+export function annotateEffects(code: string, id: string): AnnotateResult {
+  let ast: t.File
+  try {
+    ast = parse(code, {
+      sourceType: "module",
+      plugins: ["typescript", "jsx"],
+      sourceFilename: id
+    })
+  } catch {
+    return { code, transformed: false }
+  }
+
+  let hasTransformed = false
+
+  traverse(ast, {
+    CallExpression(path: NodePath<t.CallExpression>) {
+      // Skip if already has pure annotation
+      if (hasPureAnnotation(path.node)) return
+
+      // Only annotate Effect module calls
+      if (!isEffectModuleCall(path.node)) return
+
+      // Only annotate in useful contexts
+      if (!isInAnnotatableContext(path)) return
+
+      // Add @__PURE__ annotation
+      t.addComment(path.node, "leading", "#__PURE__", false)
+      hasTransformed = true
+    }
+  })
+
+  if (!hasTransformed) {
+    return { code, transformed: false }
+  }
+
+  const result = generate(ast, {
+    sourceMaps: true,
+    sourceFileName: id,
+    comments: true
+  }, code)
+
+  return {
+    code: result.code,
+    map: result.map,
+    transformed: true
+  }
+}

package/src/esbuild.ts

@@ -0,0 +1,18 @@
+/**
+ * esbuild plugin for Effect source location tracing.
+ *
+ * @example
+ * ```ts
+ * import esbuild from "esbuild"
+ * import effectSourceTrace from "@effect/unplugin/esbuild"
+ *
+ * esbuild.build({
+ *   plugins: [effectSourceTrace()]
+ * })
+ * ```
+ *
+ * @since 0.0.1
+ */
+import unplugin from "./index.ts"
+
+export default unplugin.esbuild

package/src/index.ts

@@ -0,0 +1,119 @@
+/**
+ * Build-time AST transformer for Effect source location tracing and auto-instrumentation.
+ *
+ * This plugin provides two features:
+ * 1. **Source Tracing**: Transforms `yield*` expressions inside `Effect.gen()` to
+ *    inject source location information via `CurrentStackFrame`.
+ * 2. **Span Instrumentation**: Wraps Effect combinators with `withSpan()` for
+ *    automatic distributed tracing.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from "vite"
+ * import effectSourceTrace from "@effect/unplugin/vite"
+ *
+ * export default defineConfig({
+ *   plugins: [effectSourceTrace({
+ *     // Enable source tracing (default: true)
+ *     sourceTrace: true,
+ *     // Enable span instrumentation
+ *     spans: {
+ *       enabled: true,
+ *       include: ["gen", "fork", "all", "forEach"]
+ *     }
+ *   })]
+ * })
+ * ```
+ *
+ * @since 0.0.1
+ */
+import { createUnplugin, type TransformResult as UnpluginTransformResult } from "unplugin"
+import { annotateEffects } from "./annotateEffects.ts"
+import { transform } from "./sourceTrace.ts"
+import type { FilterPattern, SourceTraceOptions } from "./types.ts"
+
+export { type AnnotateResult, annotateEffects } from "./annotateEffects.ts"
+export { type TransformResult } from "./sourceTrace.ts"
+export type { FilterPattern, InstrumentableEffect, SourceTraceOptions, SpanInstrumentationOptions } from "./types.ts"
+
+const defaultInclude: ReadonlyArray<string | RegExp> = [/\.[jt]sx?$/]
+const defaultExclude: ReadonlyArray<string | RegExp> = [/node_modules/]
+
+function toArray(value: FilterPattern | undefined): ReadonlyArray<string | RegExp> {
+  if (value === undefined) return []
+  if (Array.isArray(value)) return value
+  return [value as string | RegExp]
+}
+
+function createFilter(
+  include: FilterPattern | undefined,
+  exclude: FilterPattern | undefined
+): (id: string) => boolean {
+  const includePatterns = toArray(include ?? defaultInclude)
+  const excludePatterns = toArray(exclude ?? defaultExclude)
+
+  return (id: string): boolean => {
+    for (const pattern of excludePatterns) {
+      if (typeof pattern === "string" ? id.includes(pattern) : pattern.test(id)) {
+        return false
+      }
+    }
+    for (const pattern of includePatterns) {
+      if (typeof pattern === "string" ? id.includes(pattern) : pattern.test(id)) {
+        return true
+      }
+    }
+    return false
+  }
+}
+
+/**
+ * Creates the Effect source trace unplugin.
+ *
+ * @since 0.0.1
+ * @category unplugin
+ */
+export const unplugin = createUnplugin<SourceTraceOptions | undefined>((options = {}) => {
+  const filter = createFilter(options.include, options.exclude)
+
+  return {
+    name: "effect-source-trace",
+    enforce: "pre",
+
+    transformInclude(id) {
+      return filter(id)
+    },
+
+    transform(code, id) {
+      let currentCode = code
+      let hasTransformed = false
+      let finalMap: unknown
+
+      // Run source trace and span instrumentation
+      const traceResult = transform(currentCode, id, options)
+      if (traceResult.transformed) {
+        currentCode = traceResult.code
+        finalMap = traceResult.map
+        hasTransformed = true
+      }
+
+      // Run annotateEffects if enabled
+      if (options.annotateEffects) {
+        const annotateResult = annotateEffects(currentCode, id)
+        if (annotateResult.transformed) {
+          currentCode = annotateResult.code
+          finalMap = annotateResult.map
+          hasTransformed = true
+        }
+      }
+
+      if (!hasTransformed) {
+        return null
+      }
+      return { code: currentCode, map: finalMap } as UnpluginTransformResult
+    }
+  }
+})
+
+export default unplugin

package/src/rollup.ts

@@ -0,0 +1,18 @@
+/**
+ * Rollup plugin for Effect source location tracing.
+ *
+ * @example
+ * ```ts
+ * // rollup.config.js
+ * import effectSourceTrace from "@effect/unplugin/rollup"
+ *
+ * export default {
+ *   plugins: [effectSourceTrace()]
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+import unplugin from "./index.ts"
+
+export default unplugin.rollup