@clayroach/unplugin 0.1.0-source-trace.2

package/src/transformers/sourceTrace.ts

@@ -0,0 +1,102 @@
+/**
+ * Source location trace transformer.
+ *
+ * This transformer injects source location metadata into Effect.gen yield expressions.
+ * It transforms `yield* _(effect)` into `yield* _(effect, trace)` where trace is a
+ * hoisted SourceLocation object.
+ *
+ * @since 0.1.0
+ */
+import type { NodePath, Visitor } from "@babel/traverse"
+import * as t from "@babel/types"
+import { isYieldAdapterCall } from "../utils/effectDetection.js"
+import {
+  createHoistingState,
+  extractLabelFromParent,
+  getOrCreateTraceIdentifier,
+  type HoistingState
+} from "../utils/hoisting.js"
+
+/**
+ * Options for the source trace transformer.
+ */
+export interface SourceTraceOptions {
+  /**
+   * Filter function to determine if a file should be transformed.
+   * Defaults to transforming all .ts and .tsx files.
+   */
+  readonly filter?: (filename: string) => boolean
+}
+
+/**
+ * State passed through the transformer.
+ */
+interface TransformState {
+  filename: string
+  hoisting: HoistingState
+}
+
+/**
+ * Creates a Babel visitor that injects source trace metadata into Effect.gen yields.
+ */
+export function createSourceTraceVisitor(
+  filename: string,
+  _options?: SourceTraceOptions
+): Visitor<TransformState> {
+  return {
+    Program: {
+      enter(_path, state) {
+        state.filename = filename
+        state.hoisting = createHoistingState()
+      },
+      exit(path, state) {
+        // Prepend all hoisted statements to the program body
+        if (state.hoisting.statements.length > 0) {
+          path.unshiftContainer("body", state.hoisting.statements)
+        }
+      }
+    },
+
+    YieldExpression(path: NodePath<t.YieldExpression>, state) {
+      const node = path.node
+
+      // Only transform yield* _(effect) patterns
+      if (!isYieldAdapterCall(node)) {
+        return
+      }
+
+      // Get source location
+      const loc = node.loc
+      if (!loc) return
+
+      // Extract label from parent (e.g., `const user = yield* _(...)`)
+      const label = extractLabelFromParent(path)
+
+      // Get or create hoisted trace identifier
+      const traceId = getOrCreateTraceIdentifier(
+        state.hoisting,
+        state.filename,
+        loc.start.line,
+        loc.start.column,
+        label
+      )
+
+      // Inject trace as second argument: _(effect) -> _(effect, trace)
+      const callExpr = node.argument as t.CallExpression
+      callExpr.arguments.push(t.cloneNode(traceId))
+    }
+  }
+}
+
+/**
+ * Creates the source trace transformer plugin.
+ */
+export function sourceTraceTransformer(options?: SourceTraceOptions): {
+  visitor: Visitor<TransformState>
+  name: string
+} {
+  return {
+    name: "effect-source-trace",
+    visitor: createSourceTraceVisitor("", options)
+  }
+}

package/src/utils/effectDetection.ts

@@ -0,0 +1,81 @@
+/**
+ * Utilities for detecting Effect patterns in AST nodes.
+ *
+ * @since 0.1.0
+ */
+import type * as t from "@babel/types"
+
+/**
+ * Checks if a CallExpression is `Effect.gen(...)`.
+ */
+export function isEffectGenCall(node: t.Node): node is t.CallExpression {
+  if (node.type !== "CallExpression") return false
+
+  const callee = node.callee
+
+  // Match Effect.gen(...)
+  if (
+    callee.type === "MemberExpression" &&
+    callee.object.type === "Identifier" &&
+    callee.object.name === "Effect" &&
+    callee.property.type === "Identifier" &&
+    callee.property.name === "gen"
+  ) {
+    return true
+  }
+
+  // Match _.gen(...) where _ is an alias for Effect
+  if (
+    callee.type === "MemberExpression" &&
+    callee.property.type === "Identifier" &&
+    callee.property.name === "gen"
+  ) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Minimal path-like interface for AST traversal.
+ * This mirrors the essential properties of Babel's NodePath without importing the full type.
+ */
+interface PathLike {
+  parent?: t.Node | null
+  parentPath?: PathLike | null
+}
+
+/**
+ * Checks if a node is inside an Effect.gen generator function.
+ * This walks up the AST to find if there's an enclosing generator function
+ * that is an argument to Effect.gen.
+ */
+export function isInsideEffectGen(path: PathLike): boolean {
+  let current = path.parentPath
+  while (current) {
+    const node = current.parent as t.Node | undefined
+    if (node && isEffectGenCall(node)) {
+      return true
+    }
+    current = current.parentPath
+  }
+  return false
+}
+
+/**
+ * Checks if a CallExpression is a call to the adapter function `_()`.
+ * The adapter is the first argument passed to the generator function.
+ */
+export function isAdapterCall(node: t.CallExpression): boolean {
+  return node.callee.type === "Identifier" && node.callee.name === "_"
+}
+
+/**
+ * Checks if a YieldExpression is a `yield* _(effect)` pattern.
+ */
+export function isYieldAdapterCall(node: t.YieldExpression): boolean {
+  if (!node.delegate) return false // Must be yield*, not yield
+  if (!node.argument) return false
+  if (node.argument.type !== "CallExpression") return false
+  return isAdapterCall(node.argument)
+}

package/src/utils/hoisting.ts

@@ -0,0 +1,132 @@
+/**
+ * Utilities for hoisting trace metadata to module scope.
+ *
+ * @since 0.1.0
+ */
+import * as t from "@babel/types"
+
+/**
+ * State for tracking hoisted trace declarations.
+ */
+export interface HoistingState {
+  /** Map from dedup key to hoisted identifier */
+  readonly hoistedTraces: Map<string, t.Identifier>
+  /** Counter for generating unique identifiers */
+  counter: number
+  /** Statements to prepend to the program body */
+  readonly statements: Array<t.Statement>
+}
+
+/**
+ * Creates a new hoisting state.
+ */
+export function createHoistingState(): HoistingState {
+  return {
+    hoistedTraces: new Map(),
+    counter: 0,
+    statements: []
+  }
+}
+
+/**
+ * Creates a unique deduplication key for a source location.
+ * Uses line:column to disambiguate multiple yields on the same line.
+ */
+export function createDedupKey(
+  filename: string,
+  line: number,
+  column: number
+): string {
+  return `${filename}:${line}:${column}`
+}
+
+/**
+ * Gets or creates a hoisted trace identifier for the given source location.
+ */
+export function getOrCreateTraceIdentifier(
+  state: HoistingState,
+  filename: string,
+  line: number,
+  column: number,
+  label?: string
+): t.Identifier {
+  const key = createDedupKey(filename, line, column)
+
+  let identifier = state.hoistedTraces.get(key)
+  if (identifier) {
+    return identifier
+  }
+
+  // Create new identifier
+  identifier = t.identifier(`_trace${state.counter++}`)
+  state.hoistedTraces.set(key, identifier)
+
+  // Create the SourceLocation object literal
+  const properties: Array<t.ObjectProperty> = [
+    t.objectProperty(
+      t.identifier("_tag"),
+      t.stringLiteral("SourceLocation")
+    ),
+    t.objectProperty(
+      t.identifier("path"),
+      t.stringLiteral(filename)
+    ),
+    t.objectProperty(
+      t.identifier("line"),
+      t.numericLiteral(line)
+    ),
+    t.objectProperty(
+      t.identifier("column"),
+      t.numericLiteral(column)
+    )
+  ]
+
+  if (label) {
+    properties.push(
+      t.objectProperty(
+        t.identifier("label"),
+        t.stringLiteral(label)
+      )
+    )
+  }
+
+  // Wrap in Symbol.for call to add the type tag
+  const traceObject = t.objectExpression([
+    t.objectProperty(
+      t.callExpression(
+        t.memberExpression(t.identifier("Symbol"), t.identifier("for")),
+        [t.stringLiteral("effect/SourceLocation")]
+      ),
+      t.callExpression(
+        t.memberExpression(t.identifier("Symbol"), t.identifier("for")),
+        [t.stringLiteral("effect/SourceLocation")]
+      ),
+      true // computed property
+    ),
+    ...properties
+  ])
+
+  // Create variable declaration
+  const declaration = t.variableDeclaration("const", [
+    t.variableDeclarator(identifier, traceObject)
+  ])
+
+  state.statements.push(declaration)
+
+  return identifier
+}
+
+/**
+ * Extracts a label from a VariableDeclarator if the yield is part of an assignment.
+ * For example: `const user = yield* _(fetchUser(id))` extracts "user"
+ */
+export function extractLabelFromParent(path: {
+  parent?: t.Node | null
+  parentPath?: { node?: t.Node | null } | null
+}): string | undefined {
+  const parent = path.parent
+  if (parent?.type === "VariableDeclarator" && parent.id.type === "Identifier") {
+    return parent.id.name
+  }
+  return undefined
+}

package/src/vite.ts

@@ -0,0 +1,29 @@
+/**
+ * Vite plugin export for @effect/unplugin.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import effectPlugin from "@effect/unplugin/vite"
+ *
+ * export default {
+ *   plugins: [
+ *     effectPlugin({
+ *       sourceTrace: true
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+import { type EffectPluginOptions, unplugin } from "./index.js"
+
+/**
+ * Vite plugin for Effect transformations.
+ *
+ * @since 0.1.0
+ */
+export default unplugin.vite
+
+export type { EffectPluginOptions }

package/src/webpack.ts

@@ -0,0 +1,29 @@
+/**
+ * Webpack plugin export for @effect/unplugin.
+ *
+ * @example
+ * ```typescript
+ * // webpack.config.js
+ * const effectPlugin = require("@effect/unplugin/webpack").default
+ *
+ * module.exports = {
+ *   plugins: [
+ *     effectPlugin({
+ *       sourceTrace: true
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ */
+import { type EffectPluginOptions, unplugin } from "./index.js"
+
+/**
+ * Webpack plugin for Effect transformations.
+ *
+ * @since 0.1.0
+ */
+export default unplugin.webpack
+
+export type { EffectPluginOptions }

package/vite/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": [],
+  "main": "../dist/cjs/vite.js",
+  "module": "../dist/esm/vite.js",
+  "types": "../dist/dts/vite.d.ts"
+}

package/webpack/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": [],
+  "main": "../dist/cjs/webpack.js",
+  "module": "../dist/esm/webpack.js",
+  "types": "../dist/dts/webpack.d.ts"
+}