@danielfgray/pg-sourcerer 0.3.0 → 0.4.0

package/dist/runtime/registry.d.ts

@@ -0,0 +1,268 @@
+import { Context, Effect, Schema } from "effect";
+import type { Capability, SymbolDeclaration, SymbolRef, SymbolHandle } from "./types.js";
+declare const SymbolCollision_base: Schema.TaggedErrorClass<SymbolCollision, "SymbolCollision", {
+    readonly _tag: Schema.tag<"SymbolCollision">;
+} & {
+    message: typeof Schema.String;
+    capability: typeof Schema.String;
+    existingSymbol: typeof Schema.String;
+    newSymbol: typeof Schema.String;
+}>;
+/**
+ * Error thrown when two plugins try to register the same capability.
+ */
+export declare class SymbolCollision extends SymbolCollision_base {
+}
+declare const CapabilityNotFound_base: Schema.TaggedErrorClass<CapabilityNotFound, "CapabilityNotFound", {
+    readonly _tag: Schema.tag<"CapabilityNotFound">;
+} & {
+    message: typeof Schema.String;
+    capability: typeof Schema.String;
+}>;
+/**
+ * Error when trying to get a handle for an unregistered capability.
+ */
+export declare class CapabilityNotFound extends CapabilityNotFound_base {
+}
+declare const CategoryConflict_base: Schema.TaggedErrorClass<CategoryConflict, "CategoryConflict", {
+    readonly _tag: Schema.tag<"CategoryConflict">;
+} & {
+    message: typeof Schema.String;
+    category: typeof Schema.String;
+    existingProvider: typeof Schema.String;
+    newProvider: typeof Schema.String;
+}>;
+/**
+ * Error when multiple plugins try to provide the same capability category.
+ */
+export declare class CategoryConflict extends CategoryConflict_base {
+}
+/**
+ * Creates a SymbolHandle that tracks cross-references.
+ *
+ * @param decl - The symbol being referenced
+ * @param metadata - Optional metadata from render phase (may include consume callback)
+ * @param onReference - Callback when ref() or call() is invoked (for import tracking)
+ */
+export declare function createSymbolHandle(decl: SymbolDeclaration, metadata: unknown | undefined, onReference?: (capability: Capability) => void): SymbolHandle;
+/**
+ * Service interface for SymbolRegistry - what plugins see.
+ */
+export interface SymbolRegistryService {
+    /** Resolve a capability to its symbol reference */
+    readonly resolve: (capability: Capability) => SymbolRef | undefined;
+    /** Get a handle for importing another symbol (tracks cross-references) */
+    readonly import: (capability: Capability) => SymbolHandle;
+    /** Query for capabilities matching a prefix pattern */
+    readonly query: (pattern: string) => readonly SymbolDeclaration[];
+    /** Check if a capability is registered */
+    readonly has: (capability: Capability) => boolean;
+    /** Get rendered metadata for a capability */
+    readonly getMetadata: (capability: Capability) => unknown;
+    /**
+     * Get declarations owned by the current plugin.
+     * Returns only the symbols declared by this plugin in Phase 1.
+     */
+    readonly own: () => readonly SymbolDeclaration[];
+    /**
+     * Scope cross-reference tracking to a single symbol.
+     * All `import().ref()` calls within the callback are attributed
+     * only to the specified capability, not all plugin capabilities.
+     *
+     * @example
+     * ```typescript
+     * for (const decl of registry.own()) {
+     *   registry.forSymbol(decl.capability, () => {
+     *     const queryFn = registry.import(`queries:kysely:${entityName}`);
+     *     queryFn.ref(); // Only attributed to decl.capability
+     *   });
+     * }
+     * ```
+     */
+    readonly forSymbol: <T>(capability: Capability, fn: () => T) => T;
+}
+declare const SymbolRegistry_base: Context.TagClass<SymbolRegistry, "SymbolRegistry", SymbolRegistryService>;
+/**
+ * Effect Context tag for SymbolRegistry service.
+ * Plugins access this in render phase via `yield* SymbolRegistry`.
+ */
+export declare class SymbolRegistry extends SymbolRegistry_base {
+}
+/**
+ * Internal registry implementation that tracks all declared symbols.
+ *
+ * Used during the two-phase plugin execution:
+ * 1. Declare phase: Plugins register symbols via register()
+ * 2. Render phase: Plugins lookup symbols via resolve()/import()
+ *
+ * During render phase, tracks cross-references between capabilities
+ * for import generation in the emit phase.
+ */
+export declare class SymbolRegistryImpl {
+    private symbols;
+    private rendered;
+    private referenceCallbacks;
+    /**
+     * Category providers: Maps category name -> provider plugin name.
+     * e.g., "queries" -> "kysely", "schema" -> "zod"
+     * Used to resolve generic capability prefixes to implementation-specific ones.
+     */
+    private categoryProviders;
+    /**
+     * Cross-reference tracking: Maps source capability -> set of referenced capabilities.
+     * Populated during render phase when registry.import(cap).ref() is called.
+     */
+    private references;
+    /**
+     * Current capabilities being rendered. Set by orchestrator before calling render().
+     * When a handle's ref()/call() is invoked, edges are added from these to the target.
+     *
+     * When forSymbol() is active, this contains only the single scoped capability.
+     */
+    private currentCapabilities;
+    /**
+     * Declarations owned by the current plugin.
+     * Set by orchestrator before render phase.
+     */
+    private ownedDeclarations;
+    /**
+     * Stack for nested forSymbol() calls (though nesting is unusual).
+     * Stores the previous currentCapabilities to restore after forSymbol() completes.
+     */
+    private capabilityStack;
+    /**
+     * Register a symbol declaration. Called during declare phase.
+     * Returns Effect that fails with SymbolCollision if capability already registered.
+     */
+    register(decl: SymbolDeclaration): Effect.Effect<void, SymbolCollision>;
+    /**
+     * Store rendered output for a symbol. Called during render phase.
+     */
+    setRendered(capability: Capability, node: unknown, metadata?: unknown): void;
+    /**
+     * Get rendered metadata for a capability.
+     */
+    getRenderedMetadata(capability: Capability): unknown;
+    /**
+     * Register multiple declarations at once.
+     */
+    registerAll(decls: readonly SymbolDeclaration[]): Effect.Effect<void, SymbolCollision>;
+    /**
+     * Register a plugin as the provider for a capability category.
+     * Only one plugin can provide each category.
+     *
+     * @param category - Category name (e.g., "queries", "schema")
+     * @param pluginName - Name of the plugin providing this category
+     */
+    registerCategoryProvider(category: string, pluginName: string): Effect.Effect<void, CategoryConflict>;
+    /**
+     * Get the provider name for a category.
+     */
+    getCategoryProvider(category: string): string | undefined;
+    /**
+     * Resolve a generic capability to implementation-specific.
+     *
+     * Examples:
+     * - "queries:User:findById" → "queries:kysely:User:findById" (if kysely provides queries)
+     * - "schema:UserInsert" → "schema:zod:UserInsert" (if zod provides schema)
+     * - "queries:kysely:User:findById" → unchanged (already specific)
+     * - "type:User" → unchanged (no category provider needed)
+     */
+    resolveCapability(capability: Capability): Capability;
+    /**
+     * Resolve a capability to its symbol reference.
+     * Automatically resolves generic capabilities to implementation-specific.
+     * Returns undefined if not found.
+     */
+    resolve(capability: Capability): SymbolRef | undefined;
+    /**
+     * Check if a capability is registered.
+     * Automatically resolves generic capabilities to implementation-specific.
+     */
+    has(capability: Capability): boolean;
+    /**
+     * Register a callback to be invoked when a symbol is referenced.
+     * Used for import tracking across files.
+     */
+    onReference(capability: Capability, callback: (capability: Capability) => void): void;
+    /**
+     * Get a SymbolHandle for referencing another symbol.
+     * The handle tracks when ref()/call() are used for import generation.
+     * Automatically resolves generic capabilities to implementation-specific.
+     * Returns Effect that fails with CapabilityNotFound if not registered.
+     */
+    getHandle(capability: Capability): Effect.Effect<SymbolHandle, CapabilityNotFound>;
+    /**
+     * Get a SymbolHandle synchronously (for service interface).
+     * Automatically resolves generic capabilities to implementation-specific.
+     * Throws if not found.
+     */
+    import(capability: Capability): SymbolHandle;
+    /**
+     * Get all registered symbols.
+     */
+    all(): readonly SymbolDeclaration[];
+    /**
+     * Get symbols that match a capability pattern.
+     * Pattern uses simple prefix matching: "type:" matches all types.
+     * Note: For category-based queries, use the implementation-specific prefix
+     * (e.g., "queries:kysely:") or query by category pattern (e.g., "queries:").
+     */
+    query(pattern: string): readonly SymbolDeclaration[];
+    /**
+     * Get the declaration for a specific capability.
+     * Automatically resolves generic capabilities to implementation-specific.
+     */
+    get(capability: Capability): SymbolDeclaration | undefined;
+    /**
+     * Set the current capabilities being rendered.
+     * Called by orchestrator before each plugin's render() phase.
+     */
+    setCurrentCapabilities(caps: readonly Capability[]): void;
+    /**
+     * Clear current capabilities context.
+     * Called by orchestrator after each plugin's render() completes.
+     */
+    clearCurrentCapabilities(): void;
+    /**
+     * Set the declarations owned by the current plugin.
+     * Called by orchestrator before render phase.
+     */
+    setOwnedDeclarations(decls: readonly SymbolDeclaration[]): void;
+    /**
+     * Get declarations owned by the current plugin.
+     * Returns only the symbols declared by this plugin in Phase 1.
+     */
+    own(): readonly SymbolDeclaration[];
+    /**
+     * Scope cross-reference tracking to a single symbol.
+     * All `import().ref()` calls within the callback are attributed
+     * only to the specified capability.
+     *
+     * @param capability - The capability to scope refs to
+     * @param fn - Function to execute with scoped context
+     * @returns The result of fn()
+     */
+    forSymbol<T>(capability: Capability, fn: () => T): T;
+    /**
+     * Record a reference from current capabilities to target.
+     * Called internally when SymbolHandle.ref() or .call() is invoked.
+     */
+    private recordReference;
+    /**
+     * Get all capabilities referenced by a given capability.
+     */
+    getReferences(capability: Capability): readonly Capability[];
+    /**
+     * Get the full reference map for emit phase.
+     * Maps: source capability -> capabilities it references
+     */
+    getAllReferences(): ReadonlyMap<Capability, readonly Capability[]>;
+    /**
+     * Create a service instance that conforms to SymbolRegistryService.
+     * Used by orchestrator to provide the service to plugins.
+     */
+    toService(): SymbolRegistryService;
+}
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/runtime/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/runtime/registry.ts"],"names":[],"mappings":"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"}