@danielfgray/pg-sourcerer 0.3.0 → 0.5.0

package/dist/shared/query-types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Query descriptor types for SQL code generation
+ *
+ * These types describe SQL queries in a way that plugins can consume
+ * to generate typed function wrappers. They are produced by `hex` (the SQL
+ * template builder) and consumed by query plugins.
+ */
+/**
+ * Complete description of a generated query.
+ *
+ * This is the primary type that `hex.build()` produces and query plugins consume.
+ */
+export interface QueryDescriptor {
+    /** Function name, e.g., "findUserById", "insertUser" */
+    readonly name: string;
+    /** Entity this query operates on, e.g., "User" */
+    readonly entityName: string;
+    /** SQL operation type */
+    readonly operation: QueryOperation;
+    /** Lookup variant, e.g., "byId", "byEmail" (for distinguishing similar queries) */
+    readonly variant?: string;
+    /** SQL template with positional parameters ($1, $2, etc.) */
+    readonly sql: string;
+    /** Input parameters */
+    readonly params: readonly ParamDescriptor[];
+    /** Return type description */
+    readonly returns: ReturnDescriptor;
+    /** Optional metadata for advanced use cases */
+    readonly meta?: QueryMetadata;
+}
+/**
+ * Describes a single query parameter.
+ */
+export interface ParamDescriptor {
+    /** Parameter name, e.g., "id", "email" */
+    readonly name: string;
+    /** TypeScript type string, e.g., "string", "number", "string | null" */
+    readonly tsType: string;
+    /** PostgreSQL type, e.g., "uuid", "text", "integer" */
+    readonly pgType: string;
+    /** Whether the parameter accepts null */
+    readonly nullable: boolean;
+    /** Whether the parameter has a default value (can be omitted) */
+    readonly hasDefault?: boolean;
+}
+/**
+ * Describes the return type of a query.
+ */
+export interface ReturnDescriptor {
+    /** How many rows are expected */
+    readonly mode: ReturnMode;
+    /** Fields in the return type (empty for 'affected' or 'void') */
+    readonly fields: readonly FieldDescriptor[];
+}
+/**
+ * Describes a field in the query return type.
+ */
+export interface FieldDescriptor {
+    /** Column name or alias */
+    readonly name: string;
+    /** TypeScript type string */
+    readonly tsType: string;
+    /** PostgreSQL type */
+    readonly pgType: string;
+    /** Whether the field can be null */
+    readonly nullable: boolean;
+    /** Whether this is an array type */
+    readonly isArray?: boolean;
+}
+/**
+ * Optional metadata for advanced query use cases.
+ */
+export interface QueryMetadata {
+    /** Fully qualified table name (schema.table) */
+    readonly table: string;
+    /** Indexes used by this query */
+    readonly indexes?: readonly string[];
+    /** Generated from table/column comments */
+    readonly comment?: string;
+}
+/**
+ * SQL operation categories.
+ */
+export type QueryOperation = "select" | "insert" | "update" | "delete" | "upsert";
+/**
+ * Query return cardinality modes.
+ *
+ * - `one`: Exactly one row expected (throws if 0 or >1)
+ * - `oneOrNone`: Zero or one row (returns T | null)
+ * - `many`: Zero or more rows (returns T[])
+ * - `affected`: Returns affected row count (number)
+ * - `void`: Returns nothing
+ */
+export type ReturnMode = "one" | "oneOrNone" | "many" | "affected" | "void";
+//# sourceMappingURL=query-types.d.ts.map

package/dist/shared/query-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-types.d.ts","sourceRoot":"","sources":["../../src/shared/query-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IAEnC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAE5C,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IAEnC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;CAC/B;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAElF;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC"}

package/dist/shared/query-types.js

@@ -0,0 +1,9 @@
+/**
+ * Query descriptor types for SQL code generation
+ *
+ * These types describe SQL queries in a way that plugins can consume
+ * to generate typed function wrappers. They are produced by `hex` (the SQL
+ * template builder) and consumed by query plugins.
+ */
+export {};
+//# sourceMappingURL=query-types.js.map

package/dist/shared/query-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-types.js","sourceRoot":"","sources":["../../src/shared/query-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/testing.d.ts

@@ -1,56 +1,144 @@
 /**
  * Testing Utilities
  *
- * Provides reusable test layers and helpers for plugin testing.
+ * Helpers for testing plugins and the generation pipeline.
+ *
+ * ## Plugin Testing
+ *
+ * ```typescript
+ * import { testPlugin, testIR, testConfig } from "pg-sourcerer/testing"
+ *
+ * it.effect("generates types", () =>
+ *   Effect.gen(function* () {
+ *     const result = yield* testPlugin(myPlugin, {
+ *       ir: testIR({ entities: [...] }),
+ *     })
+ *     expect(result.declarations).toHaveLength(1)
+ *   })
+ * )
+ * ```
+ *
+ * ## IR Building
+ *
+ * Use testIRWithEntities with real entities from ir-builder, or create
+ * minimal stubs for unit tests that don't need full introspection data.
  */
-import { Layer } from "effect";
-import { PluginMeta } from "./services/plugin-meta.js";
-import { IR } from "./services/ir.js";
-import type { SemanticIR } from "./ir/semantic-ir.js";
+import { Effect } from "effect";
+import type { Plugin } from "./runtime/types.js";
+import { type OrchestratorConfig, type OrchestratorResult } from "./runtime/orchestrator.js";
+import { type EmittedFile } from "./runtime/emit.js";
+import type { SemanticIR, Entity } from "./ir/semantic-ir.js";
+import { type CoreInflection } from "./services/inflection.js";
+import { type TypeHintRegistry } from "./services/type-hints.js";
 /**
- * Base test layers for direct plugin testing.
+ * Create a minimal SemanticIR for testing.
  *
- * Provides all shared services except IR and PluginMeta,
- * which are test-specific.
+ * Most tests just need an empty or partial IR. For tests that don't need
+ * real entity structures, use actual IRBuilder or provide entities directly.
+ */
+export declare function testIR(overrides?: Partial<SemanticIR>): SemanticIR;
+/**
+ * Create a SemanticIR with entities from a map or array.
  *
- * Usage:
+ * @example
  * ```typescript
- * const TestLayer = Layer.mergeAll(
- *   PluginTestLayers,
- *   Layer.succeed(IR, testIR),
- *   Layer.succeed(PluginMeta, { name: "test-plugin" }),
+ * // From array (uses entity.name as key)
+ * const ir = testIRWithEntities([userEntity, postEntity])
+ *
+ * // From map
+ * const ir = testIRWithEntities(new Map([["User", userEntity]]))
+ * ```
+ */
+export declare function testIRWithEntities(entities: ReadonlyMap<string, Entity> | readonly Entity[]): SemanticIR;
+/**
+ * Load introspection fixture and build IR from it.
+ *
+ * Returns an Effect that loads the pre-captured introspection data
+ * and builds IR using the real IR builder service.
+ *
+ * @example
+ * ```typescript
+ * it.effect("uses fixture data", () =>
+ *   Effect.gen(function* () {
+ *     const ir = yield* testIRFromFixture(["app_public"]);
+ *     const userEntity = ir.entities.get("User");
+ *     expect(userEntity).toBeDefined();
+ *   })
  * )
  * ```
  */
-export declare const PluginTestLayers: Layer.Layer<import("./index.js").Inflection | import("./testing.js").Symbols | import("./testing.js").Emissions | import("./index.js").TypeHints | import("./index.js").ArtifactStore, never, never>;
+export declare function testIRFromFixture(schemas?: readonly string[]): Effect.Effect<SemanticIR, unknown>;
+/**
+ * Options for testConfig.
+ */
+export interface TestConfigOptions {
+    /** IR to use (defaults to empty testIR) */
+    ir?: SemanticIR;
+    /** Inflection config */
+    inflection?: CoreInflection;
+    /** Type hints */
+    typeHints?: TypeHintRegistry;
+    /** Default file for unmatched symbols */
+    defaultFile?: string;
+    /** Output directory */
+    outputDir?: string;
+}
+/**
+ * Create an OrchestratorConfig for testing.
+ */
+export declare function testConfig(options?: TestConfigOptions): OrchestratorConfig;
+/**
+ * Options for testing a plugin.
+ */
+export interface TestPluginOptions {
+    /** IR to use (defaults to empty testIR) */
+    ir?: SemanticIR;
+    /** Inflection config */
+    inflection?: CoreInflection;
+    /** Type hints */
+    typeHints?: TypeHintRegistry;
+    /** Default file for unmatched symbols */
+    defaultFile?: string;
+    /** Output directory */
+    outputDir?: string;
+    /** Additional plugins to run before this one (for dependencies) */
+    dependencies?: readonly Plugin[];
+}
 /**
- * Create a complete test layer for a specific plugin test.
+ * Run a single plugin through the orchestrator and return results.
  *
- * @param ir - The SemanticIR to provide
- * @param pluginName - The plugin name for PluginMeta
- * @returns Layer with all services for plugin testing
+ * Useful for unit testing plugins in isolation.
  *
- * Usage:
+ * @example
  * ```typescript
- * const testIR = freezeIR(createIRBuilder(["public"]))
- * const TestLayer = createPluginTestLayer(testIR, "my-plugin")
- *
- * layer(TestLayer)("MyPlugin tests", (it) => {
- *   it.effect("generates types", () =>
- *     Effect.gen(function* () {
- *       yield* myPlugin.run(config)
- *       const emissions = yield* Emissions
- *       expect(emissions.getAll()).toHaveLength(1)
+ * it.effect("declares User type", () =>
+ *   Effect.gen(function* () {
+ *     const result = yield* testPlugin(typesPlugin)
+ *     expect(result.declarations).toContainEqual(
+ *       expect.objectContaining({ name: "User" })
+ *     )
+ *   })
+ * )
+ * ```
+ */
+export declare function testPlugin(plugin: Plugin, options?: TestPluginOptions): Effect.Effect<OrchestratorResult, unknown>;
+/**
+ * Run a plugin and emit files, returning both orchestration and emit results.
+ *
+ * @example
+ * ```typescript
+ * it.effect("generates valid TypeScript", () =>
+ *   Effect.gen(function* () {
+ *     const { files } = yield* testPluginEmit(typesPlugin, {
+ *       ir: testIRWithEntities([...]),
  *     })
- *   )
- * })
+ *     expect(files[0].content).toContain("export type User")
+ *   })
+ * )
  * ```
  */
-export declare function createPluginTestLayer(ir: SemanticIR, pluginName: string): Layer.Layer<import("./index.js").Inflection | import("./testing.js").Symbols | import("./testing.js").Emissions | import("./index.js").TypeHints | IR | import("./index.js").ArtifactStore | PluginMeta, never, never>;
-export { IR } from "./services/ir.js";
-export { PluginMeta } from "./services/plugin-meta.js";
-export { Emissions } from "./services/emissions.js";
-export { Symbols } from "./services/symbols.js";
-export { runPlugins } from "./services/plugin-runner.js";
-export { createIRBuilder, freezeIR } from "./ir/semantic-ir.js";
+export declare function testPluginEmit(plugin: Plugin, options?: TestPluginOptions): Effect.Effect<{
+    result: OrchestratorResult;
+    files: readonly EmittedFile[];
+}, unknown>;
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAM9B,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACtD,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAA;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,sMAM5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,0NAMvE;AAGD,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAA;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAQxF;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CASlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,GACxD,UAAU,CAGZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,SAAS,MAAM,EAAmB,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CASjH;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,wBAAwB;IACxB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,iBAAiB;IACjB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,kBAAkB,CAS9E;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,wBAAwB;IACxB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,iBAAiB;IACjB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAY5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAAC,MAAM,CAAC;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,EAAE,OAAO,CAAC,CAOvF"}

package/dist/testing.js

@@ -1,63 +1,155 @@
 /**
  * Testing Utilities
  *
- * Provides reusable test layers and helpers for plugin testing.
+ * Helpers for testing plugins and the generation pipeline.
+ *
+ * ## Plugin Testing
+ *
+ * ```typescript
+ * import { testPlugin, testIR, testConfig } from "pg-sourcerer/testing"
+ *
+ * it.effect("generates types", () =>
+ *   Effect.gen(function* () {
+ *     const result = yield* testPlugin(myPlugin, {
+ *       ir: testIR({ entities: [...] }),
+ *     })
+ *     expect(result.declarations).toHaveLength(1)
+ *   })
+ * )
+ * ```
+ *
+ * ## IR Building
+ *
+ * Use testIRWithEntities with real entities from ir-builder, or create
+ * minimal stubs for unit tests that don't need full introspection data.
  */
-import { Layer } from "effect";
+import { Effect } from "effect";
+import { runPlugins, } from "./runtime/orchestrator.js";
+import { emitFiles } from "./runtime/emit.js";
+import { defaultInflection } from "./services/inflection.js";
+import { emptyTypeHintRegistry } from "./services/type-hints.js";
+import { createIRBuilderService } from "./services/ir-builder.js";
 import { InflectionLive } from "./services/inflection.js";
-import { EmissionsLive } from "./services/emissions.js";
-import { SymbolsLive } from "./services/symbols.js";
-import { TypeHintsLive } from "./services/type-hints.js";
-import { ArtifactStoreLive } from "./services/artifact-store.js";
-import { PluginMeta } from "./services/plugin-meta.js";
-import { IR } from "./services/ir.js";
+// =============================================================================
+// Test IR Builders
+// =============================================================================
+/**
+ * Create a minimal SemanticIR for testing.
+ *
+ * Most tests just need an empty or partial IR. For tests that don't need
+ * real entity structures, use actual IRBuilder or provide entities directly.
+ */
+export function testIR(overrides) {
+    return {
+        schemas: ["public"],
+        entities: new Map(),
+        artifacts: new Map(),
+        extensions: [],
+        introspectedAt: new Date(),
+        ...overrides,
+    };
+}
+/**
+ * Create a SemanticIR with entities from a map or array.
+ *
+ * @example
+ * ```typescript
+ * // From array (uses entity.name as key)
+ * const ir = testIRWithEntities([userEntity, postEntity])
+ *
+ * // From map
+ * const ir = testIRWithEntities(new Map([["User", userEntity]]))
+ * ```
+ */
+export function testIRWithEntities(entities) {
+    const entityMap = Array.isArray(entities) ? new Map(entities.map(e => [e.name, e])) : entities;
+    return testIR({ entities: entityMap });
+}
 /**
- * Base test layers for direct plugin testing.
+ * Load introspection fixture and build IR from it.
  *
- * Provides all shared services except IR and PluginMeta,
- * which are test-specific.
+ * Returns an Effect that loads the pre-captured introspection data
+ * and builds IR using the real IR builder service.
  *
- * Usage:
+ * @example
  * ```typescript
- * const TestLayer = Layer.mergeAll(
- *   PluginTestLayers,
- *   Layer.succeed(IR, testIR),
- *   Layer.succeed(PluginMeta, { name: "test-plugin" }),
+ * it.effect("uses fixture data", () =>
+ *   Effect.gen(function* () {
+ *     const ir = yield* testIRFromFixture(["app_public"]);
+ *     const userEntity = ir.entities.get("User");
+ *     expect(userEntity).toBeDefined();
+ *   })
  * )
  * ```
  */
-export const PluginTestLayers = Layer.mergeAll(InflectionLive, EmissionsLive, SymbolsLive, TypeHintsLive([]), ArtifactStoreLive);
+export function testIRFromFixture(schemas = ["app_public"]) {
+    const builder = createIRBuilderService();
+    return Effect.gen(function* () {
+        const { loadIntrospectionFixture } = yield* Effect.promise(() => import("./__tests__/fixtures/index.js").then(m => ({ loadIntrospectionFixture: m.loadIntrospectionFixture })));
+        const introspection = loadIntrospectionFixture();
+        return yield* builder.build(introspection, { schemas });
+    }).pipe(Effect.provide(InflectionLive));
+}
+/**
+ * Create an OrchestratorConfig for testing.
+ */
+export function testConfig(options = {}) {
+    return {
+        plugins: [],
+        ir: options.ir ?? testIR(),
+        inflection: options.inflection ?? defaultInflection,
+        typeHints: options.typeHints ?? emptyTypeHintRegistry,
+        defaultFile: options.defaultFile ?? "index.ts",
+        outputDir: options.outputDir ?? "src/generated",
+    };
+}
 /**
- * Create a complete test layer for a specific plugin test.
+ * Run a single plugin through the orchestrator and return results.
  *
- * @param ir - The SemanticIR to provide
- * @param pluginName - The plugin name for PluginMeta
- * @returns Layer with all services for plugin testing
+ * Useful for unit testing plugins in isolation.
  *
- * Usage:
+ * @example
  * ```typescript
- * const testIR = freezeIR(createIRBuilder(["public"]))
- * const TestLayer = createPluginTestLayer(testIR, "my-plugin")
- *
- * layer(TestLayer)("MyPlugin tests", (it) => {
- *   it.effect("generates types", () =>
- *     Effect.gen(function* () {
- *       yield* myPlugin.run(config)
- *       const emissions = yield* Emissions
- *       expect(emissions.getAll()).toHaveLength(1)
+ * it.effect("declares User type", () =>
+ *   Effect.gen(function* () {
+ *     const result = yield* testPlugin(typesPlugin)
+ *     expect(result.declarations).toContainEqual(
+ *       expect.objectContaining({ name: "User" })
+ *     )
+ *   })
+ * )
+ * ```
+ */
+export function testPlugin(plugin, options = {}) {
+    const config = testConfig({
+        ir: options.ir,
+        inflection: options.inflection,
+        typeHints: options.typeHints,
+        defaultFile: options.defaultFile,
+        outputDir: options.outputDir,
+    });
+    const allPlugins = [...(options.dependencies ?? []), plugin];
+    return runPlugins({ ...config, plugins: allPlugins });
+}
+/**
+ * Run a plugin and emit files, returning both orchestration and emit results.
+ *
+ * @example
+ * ```typescript
+ * it.effect("generates valid TypeScript", () =>
+ *   Effect.gen(function* () {
+ *     const { files } = yield* testPluginEmit(typesPlugin, {
+ *       ir: testIRWithEntities([...]),
  *     })
- *   )
- * })
+ *     expect(files[0].content).toContain("export type User")
+ *   })
+ * )
  * ```
  */
-export function createPluginTestLayer(ir, pluginName) {
-    return Layer.mergeAll(PluginTestLayers, Layer.succeed(IR, ir), Layer.succeed(PluginMeta, { name: pluginName }));
+export function testPluginEmit(plugin, options = {}) {
+    return testPlugin(plugin, options).pipe(Effect.map(result => ({
+        result,
+        files: emitFiles(result),
+    })));
 }
-// Re-export commonly needed items for tests
-export { IR } from "./services/ir.js";
-export { PluginMeta } from "./services/plugin-meta.js";
-export { Emissions } from "./services/emissions.js";
-export { Symbols } from "./services/symbols.js";
-export { runPlugins } from "./services/plugin-runner.js";
-export { createIRBuilder, freezeIR } from "./ir/semantic-ir.js";
 //# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACtD,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAA;AAGrC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC,QAAQ,CAC5C,cAAc,EACd,aAAa,EACb,WAAW,EACX,aAAa,CAAC,EAAE,CAAC,EACjB,iBAAiB,CAClB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAc,EAAE,UAAkB;IACtE,OAAO,KAAK,CAAC,QAAQ,CACnB,gBAAgB,EAChB,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,EACrB,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAChD,CAAA;AACH,CAAC;AAED,4CAA4C;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAA;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/user-module.d.ts

@@ -0,0 +1,86 @@
+/**
+ * User Module Reference
+ *
+ * Provides a structured way to import user-defined modules in generated code.
+ * Paths are relative to the config file, and the system computes correct
+ * relative imports for each output file at emit time.
+ */
+/**
+ * Reference to a user-defined module for import in generated code.
+ *
+ * @example
+ * ```typescript
+ * // In pgsourcerer.config.ts
+ * import { userModule } from "pg-sourcerer";
+ *
+ * kysely({
+ *   dbImport: userModule("./db.ts", { named: ["db"] }),
+ * })
+ * ```
+ */
+export interface UserModuleRef {
+    readonly _tag: "UserModuleRef";
+    /** Path to the module, relative to the config file */
+    readonly path: string;
+    /** Named exports to import: import { foo, bar } from "..." */
+    readonly named?: readonly string[];
+    /** Default import binding: import db from "..." */
+    readonly default?: string;
+    /** Namespace import binding: import * as Db from "..." */
+    readonly namespace?: string;
+    /**
+     * Whether to validate that the requested exports exist in the module.
+     * @default true
+     */
+    readonly validate?: boolean;
+}
+/**
+ * Options for creating a user module reference.
+ */
+export interface UserModuleOptions {
+    /** Named exports to import: import { foo, bar } from "..." */
+    readonly named?: readonly string[];
+    /** Default import binding: import db from "..." */
+    readonly default?: string;
+    /** Namespace import binding: import * as Db from "..." */
+    readonly namespace?: string;
+    /**
+     * Whether to validate that the requested exports exist in the module.
+     * @default true
+     */
+    readonly validate?: boolean;
+}
+/**
+ * Create a reference to a user module for import in generated code.
+ *
+ * The path is relative to the config file location. At emit time, the system
+ * computes the correct relative import path for each generated file.
+ *
+ * @param path - Path to the module, relative to the config file
+ * @param options - Import options (what to import from the module)
+ * @returns A UserModuleRef that can be passed to plugin config
+ *
+ * @example
+ * ```typescript
+ * // Named imports
+ * userModule("./db.ts", { named: ["db", "Kysely"] })
+ * // Generates: import { db, Kysely } from "../db.js"
+ *
+ * // Default import
+ * userModule("./db.ts", { default: "db" })
+ * // Generates: import db from "../db.js"
+ *
+ * // Namespace import
+ * userModule("./db.ts", { namespace: "Db" })
+ * // Generates: import * as Db from "../db.js"
+ *
+ * // Skip validation (not recommended)
+ * userModule("./db.ts", { named: ["db"], validate: false })
+ * ```
+ */
+export declare function userModule(path: string, options: UserModuleOptions): UserModuleRef;
+/**
+ * Type guard to check if a value is a UserModuleRef.
+ */
+export declare function isUserModuleRef(value: unknown): value is UserModuleRef;
+//# sourceMappingURL=user-module.d.ts.map

package/dist/user-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-module.d.ts","sourceRoot":"","sources":["../src/user-module.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,aAAa,CASlF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAOtE"}