@grafema/util 0.3.0-beta

package/dist/queries/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Shared Types for Graph Query Utilities
+ *
+ * These types are used by findCallsInFunction, findContainingFunction,
+ * and other query utilities.
+ *
+ * @module queries/types
+ */
+/**
+ * Information about a function/method call found in code
+ */
+export interface CallInfo {
+    /** Node ID of the call site */
+    id: string;
+    /** Called function/method name */
+    name: string;
+    /** Node type: 'CALL' or 'METHOD_CALL' */
+    type: 'CALL' | 'METHOD_CALL';
+    /** Object name for method calls (e.g., 'response' for response.json()) */
+    object?: string;
+    /** Whether the call target was resolved (has CALLS edge) */
+    resolved: boolean;
+    /** Target function info if resolved */
+    target?: {
+        id: string;
+        name: string;
+        file?: string;
+        line?: number;
+    };
+    /** File where call occurs */
+    file?: string;
+    /** Line number of call */
+    line?: number;
+    /** Depth in transitive call chain (0 = direct call) */
+    depth?: number;
+}
+/**
+ * Information about a function that calls another function
+ */
+export interface CallerInfo {
+    /** Caller function ID */
+    id: string;
+    /** Caller function name */
+    name: string;
+    /** Caller function type (FUNCTION, CLASS, MODULE) */
+    type: string;
+    /** File containing the caller */
+    file?: string;
+    /** Line of the call site */
+    line?: number;
+}
+/**
+ * Options for finding calls in a function
+ */
+export interface FindCallsOptions {
+    /** Maximum depth for scope traversal (default: 10) */
+    maxDepth?: number;
+    /** Follow transitive calls (default: false) */
+    transitive?: boolean;
+    /** Maximum depth for transitive traversal (default: 5) */
+    transitiveDepth?: number;
+}
+/**
+ * Location of a value source in the graph
+ */
+export interface ValueSource {
+    /** Node ID in the graph */
+    id: string;
+    /** File path */
+    file: string;
+    /** Line number (1-based) */
+    line: number;
+}
+/**
+ * Reason why a value could not be determined statically.
+ * Used for debugging and user-facing messages.
+ */
+export type UnknownReason = 'parameter' | 'call_result' | 'implicit_return' | 'constructor_call' | 'nondeterministic' | 'max_depth' | 'no_sources';
+/**
+ * A single traced value from the graph.
+ * Represents either a concrete value (from LITERAL) or an unknown value
+ * (from PARAMETER, CALL, nondeterministic source, etc.)
+ */
+export interface TracedValue {
+    /** The literal value (undefined if unknown) */
+    value: unknown;
+    /** Source location in the codebase */
+    source: ValueSource;
+    /** Whether value could not be determined statically */
+    isUnknown: boolean;
+    /** Why the value is unknown (for debugging/display) */
+    reason?: UnknownReason;
+}
+/**
+ * Options for traceValues()
+ */
+export interface TraceValuesOptions {
+    /** Maximum traversal depth (default: 10) */
+    maxDepth?: number;
+    /** Follow DERIVES_FROM edges in addition to ASSIGNED_FROM (default: true) */
+    followDerivesFrom?: boolean;
+    /** Detect nondeterministic patterns like process.env (default: true) */
+    detectNondeterministic?: boolean;
+    /** Follow CALL_RETURNS edges to trace through function calls (default: true) */
+    followCallReturns?: boolean;
+}
+/**
+ * Aggregated result from tracing.
+ * Convenience type for consumers who don't need individual sources.
+ */
+export interface ValueSetResult {
+    /** All unique concrete values found */
+    values: unknown[];
+    /** Whether any path led to unknown value */
+    hasUnknown: boolean;
+}
+/**
+ * Edge record for traceValues
+ */
+export interface TraceValuesEdge {
+    src: string;
+    dst: string;
+    type: string;
+    metadata?: {
+        argIndex?: number;
+        isReject?: boolean;
+    };
+}
+/**
+ * Node record for traceValues
+ */
+export interface TraceValuesNode {
+    id: string;
+    type?: string;
+    nodeType?: string;
+    value?: unknown;
+    file?: string;
+    line?: number;
+    expressionType?: string;
+    object?: string;
+    property?: string;
+    className?: string;
+    name?: string;
+}
+/**
+ * Minimal graph backend interface for traceValues().
+ * Works with both RFDBServerBackend and internal Graph interface.
+ */
+export interface TraceValuesGraphBackend {
+    getNode(id: string): Promise<TraceValuesNode | null>;
+    getOutgoingEdges(nodeId: string, edgeTypes: string[] | null): Promise<TraceValuesEdge[]>;
+    /**
+     * Get incoming edges to a node (REG-334: needed for RESOLVES_TO)
+     * Required for Promise tracing - must be implemented by all backends
+     */
+    getIncomingEdges(nodeId: string, edgeTypes: string[] | null): Promise<TraceValuesEdge[]>;
+}
+/**
+ * Nondeterministic MemberExpression pattern.
+ * object.property combinations that represent external/user input.
+ */
+export interface NondeterministicPattern {
+    object: string;
+    property: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/queries/types.d.ts.map

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

package/dist/queries/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared Types for Graph Query Utilities
+ *
+ * These types are used by findCallsInFunction, findContainingFunction,
+ * and other query utilities.
+ *
+ * @module queries/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/queries/types.js.map

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

package/dist/schema/GraphSchemaExtractor.d.ts

@@ -0,0 +1,53 @@
+/**
+ * GraphSchemaExtractor - Extracts graph node/edge type schemas
+ *
+ * Usage:
+ *   const extractor = new GraphSchemaExtractor(backend);
+ *   const schema = await extractor.extract();
+ *
+ * When to use:
+ *   - Export graph schema for contract tracking
+ *   - Track node/edge type changes via checksum
+ *   - Generate graph documentation
+ */
+import type { RFDBServerBackend } from '../storage/backends/RFDBServerBackend.js';
+export interface NodeTypeSchema {
+    category: 'base' | 'namespaced';
+    namespace?: string;
+    count: number;
+}
+export interface EdgeTypeSchema {
+    count: number;
+}
+export interface GraphSchema {
+    $schema: 'grafema-graph-v1';
+    extractedAt: string;
+    nodeTypes: Record<string, NodeTypeSchema>;
+    edgeTypes: Record<string, EdgeTypeSchema>;
+    statistics: {
+        totalNodes: number;
+        totalEdges: number;
+        nodeTypeCount: number;
+        edgeTypeCount: number;
+    };
+    checksum: string;
+}
+export interface GraphExtractOptions {
+    /** Include all defined types, not just used ones (default: false) */
+    includeAll?: boolean;
+}
+export declare class GraphSchemaExtractor {
+    private backend;
+    constructor(backend: RFDBServerBackend);
+    /**
+     * Extract graph schema from current database
+     *
+     * @param options.includeAll - If true, include all defined types even with count=0
+     */
+    extract(options?: GraphExtractOptions): Promise<GraphSchema>;
+    /**
+     * Sort object keys alphabetically for deterministic output
+     */
+    private sortObject;
+}
+//# sourceMappingURL=GraphSchemaExtractor.d.ts.map

package/dist/schema/GraphSchemaExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphSchemaExtractor.d.ts","sourceRoot":"","sources":["../../src/schema/GraphSchemaExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAMlF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,UAAU,EAAE;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,oBAAoB;IACnB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,iBAAiB;IAE9C;;;;OAIG;IACG,OAAO,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAuGlE;;OAEG;IACH,OAAO,CAAC,UAAU;CAQnB"}

package/dist/schema/GraphSchemaExtractor.js

@@ -0,0 +1,125 @@
+/**
+ * GraphSchemaExtractor - Extracts graph node/edge type schemas
+ *
+ * Usage:
+ *   const extractor = new GraphSchemaExtractor(backend);
+ *   const schema = await extractor.extract();
+ *
+ * When to use:
+ *   - Export graph schema for contract tracking
+ *   - Track node/edge type changes via checksum
+ *   - Generate graph documentation
+ */
+import { createHash } from 'crypto';
+import { NODE_TYPE, NAMESPACED_TYPE, EDGE_TYPE } from '@grafema/types';
+export class GraphSchemaExtractor {
+    backend;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    /**
+     * Extract graph schema from current database
+     *
+     * @param options.includeAll - If true, include all defined types even with count=0
+     */
+    async extract(options) {
+        const includeAll = options?.includeAll ?? false;
+        // Get actual counts from graph
+        const nodeCounts = await this.backend.countNodesByType();
+        const edgeCounts = await this.backend.countEdgesByType();
+        // Build node types from definitions + counts
+        const nodeTypes = {};
+        // Base node types
+        for (const [_key, value] of Object.entries(NODE_TYPE)) {
+            nodeTypes[value] = {
+                category: 'base',
+                count: nodeCounts[value] || 0,
+            };
+        }
+        // Namespaced node types
+        for (const [_key, value] of Object.entries(NAMESPACED_TYPE)) {
+            const namespace = value.split(':')[0];
+            nodeTypes[value] = {
+                category: 'namespaced',
+                namespace,
+                count: nodeCounts[value] || 0,
+            };
+        }
+        // Add any additional types found in the graph but not in definitions
+        for (const [type, count] of Object.entries(nodeCounts)) {
+            if (!nodeTypes[type]) {
+                const namespace = type.includes(':') ? type.split(':')[0] : undefined;
+                nodeTypes[type] = {
+                    category: namespace ? 'namespaced' : 'base',
+                    namespace,
+                    count,
+                };
+            }
+        }
+        // Build edge types from definitions + counts
+        const edgeTypes = {};
+        for (const [_key, value] of Object.entries(EDGE_TYPE)) {
+            edgeTypes[value] = {
+                count: edgeCounts[value] || 0,
+            };
+        }
+        // Add any additional edge types found in the graph
+        for (const [type, count] of Object.entries(edgeCounts)) {
+            if (!edgeTypes[type]) {
+                edgeTypes[type] = { count };
+            }
+        }
+        // Calculate totals
+        const totalNodes = Object.values(nodeCounts).reduce((sum, n) => sum + n, 0);
+        const totalEdges = Object.values(edgeCounts).reduce((sum, n) => sum + n, 0);
+        // Filter out types with count=0 unless includeAll is true
+        const filteredNodeTypes = {};
+        for (const [type, info] of Object.entries(nodeTypes)) {
+            if (includeAll || info.count > 0) {
+                filteredNodeTypes[type] = info;
+            }
+        }
+        const filteredEdgeTypes = {};
+        for (const [type, info] of Object.entries(edgeTypes)) {
+            if (includeAll || info.count > 0) {
+                filteredEdgeTypes[type] = info;
+            }
+        }
+        // Sort for deterministic output
+        const sortedNodeTypes = this.sortObject(filteredNodeTypes);
+        const sortedEdgeTypes = this.sortObject(filteredEdgeTypes);
+        // Compute checksum from normalized content (based on filtered types)
+        const checksumContent = {
+            nodeTypes: Object.keys(sortedNodeTypes).sort(),
+            edgeTypes: Object.keys(sortedEdgeTypes).sort(),
+        };
+        const checksum = createHash('sha256')
+            .update(JSON.stringify(checksumContent))
+            .digest('hex');
+        return {
+            $schema: 'grafema-graph-v1',
+            extractedAt: new Date().toISOString(),
+            nodeTypes: sortedNodeTypes,
+            edgeTypes: sortedEdgeTypes,
+            statistics: {
+                totalNodes,
+                totalEdges,
+                nodeTypeCount: Object.keys(sortedNodeTypes).length,
+                edgeTypeCount: Object.keys(sortedEdgeTypes).length,
+            },
+            checksum: `sha256:${checksum}`,
+        };
+    }
+    /**
+     * Sort object keys alphabetically for deterministic output
+     */
+    sortObject(obj) {
+        const sorted = {};
+        const keys = Object.keys(obj).sort();
+        for (const key of keys) {
+            sorted[key] = obj[key];
+        }
+        return sorted;
+    }
+}
+//# sourceMappingURL=GraphSchemaExtractor.js.map

package/dist/schema/GraphSchemaExtractor.js.map

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

package/dist/schema/InterfaceSchemaExtractor.d.ts

@@ -0,0 +1,73 @@
+/**
+ * InterfaceSchemaExtractor - Extracts interface schemas from graph
+ *
+ * Usage:
+ *   const extractor = new InterfaceSchemaExtractor(backend);
+ *   const schema = await extractor.extract('ConfigSchema');
+ *
+ * When to use:
+ *   - Export interface contracts for documentation
+ *   - Track interface changes via checksum
+ *   - Generate API documentation from graph
+ */
+import type { RFDBServerBackend } from '../storage/backends/RFDBServerBackend.js';
+export interface PropertySchema {
+    type: string;
+    required: boolean;
+    readonly: boolean;
+}
+export interface InterfaceSchema {
+    $schema: 'grafema-interface-v1';
+    name: string;
+    source: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    typeParameters?: string[];
+    properties: Record<string, PropertySchema>;
+    extends: string[];
+    checksum: string;
+}
+export interface ExtractOptions {
+    /** Specific file path if multiple interfaces have same name */
+    file?: string;
+}
+export interface InterfaceNodeRecord {
+    id: string;
+    type: 'INTERFACE';
+    name: string;
+    file: string;
+    line: number;
+    column: number;
+    extends: string[];
+    properties: Array<{
+        name: string;
+        type?: string;
+        optional?: boolean;
+        readonly?: boolean;
+    }>;
+    typeParameters?: string[];
+}
+export declare class InterfaceSchemaExtractor {
+    private backend;
+    constructor(backend: RFDBServerBackend);
+    /**
+     * Extract schema for interface by name
+     *
+     * @param interfaceName - Name of the interface (e.g., 'ConfigSchema')
+     * @param options - Optional filters
+     * @returns InterfaceSchema or null if not found
+     * @throws Error if multiple interfaces match and no file specified
+     */
+    extract(interfaceName: string, options?: ExtractOptions): Promise<InterfaceSchema | null>;
+    /**
+     * Find all interfaces with given name
+     */
+    findInterfaces(name: string): Promise<InterfaceNodeRecord[]>;
+    /**
+     * Build InterfaceSchema from node record
+     */
+    private buildSchema;
+}
+//# sourceMappingURL=InterfaceSchemaExtractor.d.ts.map

package/dist/schema/InterfaceSchemaExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InterfaceSchemaExtractor.d.ts","sourceRoot":"","sources":["../../src/schema/InterfaceSchemaExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAMlF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,sBAAsB,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD,qBAAa,wBAAwB;IACvB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,iBAAiB;IAE9C;;;;;;;OAOG;IACG,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IA6B/F;;OAEG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAYlE;;OAEG;IACH,OAAO,CAAC,WAAW;CAgDpB"}

package/dist/schema/InterfaceSchemaExtractor.js

@@ -0,0 +1,113 @@
+/**
+ * InterfaceSchemaExtractor - Extracts interface schemas from graph
+ *
+ * Usage:
+ *   const extractor = new InterfaceSchemaExtractor(backend);
+ *   const schema = await extractor.extract('ConfigSchema');
+ *
+ * When to use:
+ *   - Export interface contracts for documentation
+ *   - Track interface changes via checksum
+ *   - Generate API documentation from graph
+ */
+import { createHash } from 'crypto';
+// ============================================================================
+// Extractor
+// ============================================================================
+export class InterfaceSchemaExtractor {
+    backend;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    /**
+     * Extract schema for interface by name
+     *
+     * @param interfaceName - Name of the interface (e.g., 'ConfigSchema')
+     * @param options - Optional filters
+     * @returns InterfaceSchema or null if not found
+     * @throws Error if multiple interfaces match and no file specified
+     */
+    async extract(interfaceName, options) {
+        const interfaces = await this.findInterfaces(interfaceName);
+        if (interfaces.length === 0) {
+            return null;
+        }
+        // Filter by file if specified
+        let match;
+        if (options?.file) {
+            const fileFilter = options.file;
+            const filtered = interfaces.filter(i => i.file === fileFilter || i.file.endsWith(fileFilter));
+            if (filtered.length === 0) {
+                return null;
+            }
+            match = filtered[0];
+        }
+        else if (interfaces.length > 1) {
+            const locations = interfaces.map(i => `  - ${i.file}:${i.line}`).join('\n');
+            throw new Error(`Multiple interfaces named "${interfaceName}" found:\n${locations}\n` +
+                `Use --file option to specify which one.`);
+        }
+        else {
+            match = interfaces[0];
+        }
+        return this.buildSchema(match);
+    }
+    /**
+     * Find all interfaces with given name
+     */
+    async findInterfaces(name) {
+        const result = [];
+        for await (const node of this.backend.queryNodes({ nodeType: 'INTERFACE' })) {
+            if (node.name === name) {
+                result.push(node);
+            }
+        }
+        return result;
+    }
+    /**
+     * Build InterfaceSchema from node record
+     */
+    buildSchema(node) {
+        // Sort properties alphabetically for deterministic output
+        const sortedProperties = [...(node.properties || [])].sort((a, b) => a.name.localeCompare(b.name));
+        const properties = {};
+        for (const prop of sortedProperties) {
+            properties[prop.name] = {
+                type: prop.type || 'unknown',
+                required: !prop.optional,
+                readonly: prop.readonly || false
+            };
+        }
+        // Compute checksum from normalized content
+        const checksumContent = {
+            name: node.name,
+            properties: sortedProperties.map(p => ({
+                name: p.name,
+                type: p.type,
+                optional: p.optional,
+                readonly: p.readonly
+            })),
+            extends: [...(node.extends || [])].sort(),
+            typeParameters: node.typeParameters
+        };
+        const checksum = createHash('sha256')
+            .update(JSON.stringify(checksumContent))
+            .digest('hex');
+        return {
+            $schema: 'grafema-interface-v1',
+            name: node.name,
+            source: {
+                file: node.file,
+                line: node.line,
+                column: node.column
+            },
+            ...(node.typeParameters && node.typeParameters.length > 0 && {
+                typeParameters: node.typeParameters
+            }),
+            properties,
+            extends: node.extends || [],
+            checksum: `sha256:${checksum}`
+        };
+    }
+}
+//# sourceMappingURL=InterfaceSchemaExtractor.js.map

package/dist/schema/InterfaceSchemaExtractor.js.map

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

package/dist/schema/index.d.ts

@@ -0,0 +1,5 @@
+export { InterfaceSchemaExtractor } from './InterfaceSchemaExtractor.js';
+export type { InterfaceSchema, PropertySchema, ExtractOptions } from './InterfaceSchemaExtractor.js';
+export { GraphSchemaExtractor } from './GraphSchemaExtractor.js';
+export type { GraphSchema, NodeTypeSchema, EdgeTypeSchema, GraphExtractOptions } from './GraphSchemaExtractor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAErG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/schema/index.js

@@ -0,0 +1,3 @@
+export { InterfaceSchemaExtractor } from './InterfaceSchemaExtractor.js';
+export { GraphSchemaExtractor } from './GraphSchemaExtractor.js';
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}