@kiyeonjeon21/datacontext 0.3.2 → 0.4.0

package/dist/knowledge/types.d.ts

@@ -1,6 +1,40 @@
 /**
  * Knowledge Types
- * Type definitions for the knowledge store (descriptions, rules, examples)
+ *
+ * Type definitions for the Knowledge Store / Knowledge Graph.
+ * This module defines the core data structures for storing business context
+ * about database schemas, including:
+ *
+ * - **TableDescription**: Business context for tables and columns
+ * - **TableRelationship**: Graph edges representing table relationships (FK, implicit, manual)
+ * - **QueryExample**: Verified SQL patterns with intent
+ * - **BusinessRule**: Domain constraints and conventions
+ * - **BusinessTerm**: Glossary entries for natural language → SQL translation
+ *
+ * ## Knowledge Graph Architecture
+ *
+ * The Knowledge Store is designed to evolve into a Knowledge Graph:
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │                     Knowledge Graph                             │
+ * │                                                                 │
+ * │   [Table A] ──JOINS_WITH──> [Table B] ──JOINS_WITH──> [Table C]│
+ * │       │                         │                               │
+ * │       │                         │                               │
+ * │   [Description]             [Description]                       │
+ * │   [Rules]                   [Rules]                             │
+ * │   [Examples]                [Terms]                             │
+ * │                                                                 │
+ * └─────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Multi-Database Support
+ *
+ * All references use `TableRef` which includes optional database identifier,
+ * enabling future cross-database relationship tracking.
+ *
+ * @module knowledge/types
  */
 /** Source of the knowledge entry */
 export type KnowledgeSource = 'auto' | 'user' | 'derived';
@@ -23,6 +57,115 @@ export interface KnowledgeMeta {
     /** Owner/creator */
     owner?: string;
 }
+/**
+ * Fully qualified table reference.
+ *
+ * Enables cross-database and cross-schema relationship tracking.
+ * The `database` field is optional for single-database scenarios.
+ *
+ * @example
+ * ```typescript
+ * // Single database (most common)
+ * const ref: TableRef = { schema: 'public', table: 'users' };
+ *
+ * // Multi-database (future)
+ * const ref: TableRef = { database: 'analytics', schema: 'public', table: 'events' };
+ * ```
+ */
+export interface TableRef {
+    /** Database identifier (optional for single-DB mode) */
+    database?: string;
+    /** Schema name */
+    schema: string;
+    /** Table name */
+    table: string;
+}
+/**
+ * Relationship type between tables.
+ *
+ * - `foreign_key`: Relationship derived from database FK constraint
+ * - `implicit_join`: Relationship inferred from query patterns (no FK)
+ * - `manual`: Relationship defined manually by user
+ */
+export type RelationshipType = 'foreign_key' | 'implicit_join' | 'manual';
+/**
+ * Cardinality of a table relationship.
+ *
+ * - `one-to-one`: Each row in A maps to exactly one row in B
+ * - `one-to-many`: Each row in A maps to multiple rows in B (most common for FK)
+ * - `many-to-one`: Multiple rows in A map to one row in B
+ * - `many-to-many`: Requires junction table
+ */
+export type RelationshipCardinality = 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+/**
+ * Table relationship representing a graph edge.
+ *
+ * This is the core type for the Knowledge Graph, representing how tables
+ * are connected. Relationships can be:
+ * - Auto-harvested from foreign key constraints
+ * - Inferred from query patterns (implicit joins)
+ * - Manually defined by users
+ *
+ * ## Graph Traversal
+ *
+ * Relationships enable graph queries like:
+ * - "Find all tables related to users"
+ * - "Find the shortest join path from orders to products"
+ * - "Which tables reference this column?"
+ *
+ * @example
+ * ```typescript
+ * // FK-based relationship (auto-harvested)
+ * const relationship: TableRelationship = {
+ *   type: 'table_relationship',
+ *   from: { schema: 'public', table: 'orders' },
+ *   to: { schema: 'public', table: 'users' },
+ *   relationshipType: 'foreign_key',
+ *   joinCondition: 'orders.user_id = users.id',
+ *   cardinality: 'many-to-one',
+ *   fromColumns: ['user_id'],
+ *   toColumns: ['id'],
+ *   isPreferred: true,
+ *   // ... metadata fields
+ * };
+ *
+ * // Implicit join (learned from queries)
+ * const implicit: TableRelationship = {
+ *   type: 'table_relationship',
+ *   from: { schema: 'public', table: 'events' },
+ *   to: { schema: 'public', table: 'users' },
+ *   relationshipType: 'implicit_join',
+ *   joinCondition: 'events.actor_id = users.id',
+ *   cardinality: 'many-to-one',
+ *   isPreferred: false,
+ *   notes: 'Inferred from query patterns',
+ *   // ... metadata fields
+ * };
+ * ```
+ */
+export interface TableRelationship extends KnowledgeMeta {
+    type: 'table_relationship';
+    /** Source table (FK side for foreign_key type) */
+    from: TableRef;
+    /** Target table (referenced side for foreign_key type) */
+    to: TableRef;
+    /** How this relationship was discovered */
+    relationshipType: RelationshipType;
+    /** SQL join condition */
+    joinCondition: string;
+    /** Relationship cardinality */
+    cardinality?: RelationshipCardinality;
+    /** Columns in the source table involved in the join */
+    fromColumns?: string[];
+    /** Columns in the target table involved in the join */
+    toColumns?: string[];
+    /** Whether this is the preferred join path (when multiple exist) */
+    isPreferred: boolean;
+    /** FK constraint name (if from database) */
+    constraintName?: string;
+    /** Human-readable notes about this relationship */
+    notes?: string;
+}
 /** Column description */
 export interface ColumnDescription {
     /** Column name */
@@ -126,8 +269,36 @@ export interface BusinessTerm extends KnowledgeMeta {
     isActive: boolean;
 }
 /** Union type for all knowledge entries */
-export type KnowledgeEntry = TableDescription | QueryExample | BusinessRule | BusinessTerm;
-/** Complete knowledge data structure */
+export type KnowledgeEntry = TableDescription | TableRelationship | QueryExample | BusinessRule | BusinessTerm;
+/**
+ * Complete knowledge data structure.
+ *
+ * This is the root data structure for the Knowledge Store, containing:
+ * - **Nodes**: Tables, columns (within TableDescription)
+ * - **Edges**: Relationships between tables (TableRelationship)
+ * - **Annotations**: Rules, examples, terms
+ *
+ * ## Data Model (Graph Perspective)
+ *
+ * ```
+ * Nodes:
+ *   - TableDescription (with embedded ColumnDescription[])
+ *
+ * Edges:
+ *   - TableRelationship (from → to with join condition)
+ *
+ * Annotations (attached to nodes):
+ *   - QueryExample (references tables)
+ *   - BusinessRule (applies to tables/columns)
+ *   - BusinessTerm (applies to tables/columns)
+ * ```
+ *
+ * ## Version History
+ *
+ * - `1.0.0`: Initial version (tables, examples, rules)
+ * - `1.1.0`: Added businessTerms (glossary)
+ * - `2.0.0`: Added tableRelationships (graph edges)
+ */
 export interface KnowledgeData {
     /** Version of the knowledge format */
     version: string;
@@ -137,8 +308,10 @@ export interface KnowledgeData {
     schemaHash: string;
     /** Last sync timestamp */
     lastSyncAt: string;
-    /** Table descriptions */
+    /** Table descriptions (graph nodes) */
     tableDescriptions: TableDescription[];
+    /** Table relationships (graph edges) - NEW in v2.0 */
+    tableRelationships: TableRelationship[];
     /** Query examples */
     queryExamples: QueryExample[];
     /** Business rules */
@@ -150,4 +323,79 @@ export interface KnowledgeData {
 export declare function generateId(): string;
 /** Create base metadata for a new knowledge entry */
 export declare function createKnowledgeMeta(source: KnowledgeSource, schemaHash: string, owner?: string): KnowledgeMeta;
+/**
+ * Create a TableRef from table name and optional schema/database.
+ *
+ * @param table - Table name
+ * @param schema - Schema name (defaults to 'public')
+ * @param database - Database name (optional)
+ * @returns TableRef object
+ *
+ * @example
+ * ```typescript
+ * const ref = createTableRef('users');
+ * // { schema: 'public', table: 'users' }
+ *
+ * const ref2 = createTableRef('orders', 'sales', 'analytics_db');
+ * // { database: 'analytics_db', schema: 'sales', table: 'orders' }
+ * ```
+ */
+export declare function createTableRef(table: string, schema?: string, database?: string): TableRef;
+/**
+ * Convert TableRef to a fully qualified string representation.
+ *
+ * @param ref - TableRef to stringify
+ * @returns String like "database.schema.table" or "schema.table"
+ *
+ * @example
+ * ```typescript
+ * tableRefToString({ schema: 'public', table: 'users' })
+ * // "public.users"
+ *
+ * tableRefToString({ database: 'analytics', schema: 'public', table: 'events' })
+ * // "analytics.public.events"
+ * ```
+ */
+export declare function tableRefToString(ref: TableRef): string;
+/**
+ * Check if two TableRefs refer to the same table.
+ *
+ * @param a - First TableRef
+ * @param b - Second TableRef
+ * @returns true if they refer to the same table
+ */
+export declare function tableRefsEqual(a: TableRef, b: TableRef): boolean;
+/**
+ * Create a TableRelationship from foreign key information.
+ *
+ * This is the standard way to create relationships from harvested FK data.
+ *
+ * @param params - Relationship parameters
+ * @returns Complete TableRelationship object
+ *
+ * @example
+ * ```typescript
+ * const relationship = createRelationshipFromFK({
+ *   fromTable: 'orders',
+ *   fromSchema: 'public',
+ *   fromColumn: 'user_id',
+ *   toTable: 'users',
+ *   toSchema: 'public',
+ *   toColumn: 'id',
+ *   constraintName: 'orders_user_id_fkey',
+ *   schemaHash: 'abc123',
+ * });
+ * ```
+ */
+export declare function createRelationshipFromFK(params: {
+    fromTable: string;
+    fromSchema?: string;
+    fromColumn: string;
+    toTable: string;
+    toSchema?: string;
+    toColumn: string;
+    constraintName?: string;
+    schemaHash: string;
+    database?: string;
+}): TableRelationship;
 //# sourceMappingURL=types.d.ts.map

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

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

package/dist/knowledge/types.js

@@ -1,11 +1,52 @@
 "use strict";
 /**
  * Knowledge Types
- * Type definitions for the knowledge store (descriptions, rules, examples)
+ *
+ * Type definitions for the Knowledge Store / Knowledge Graph.
+ * This module defines the core data structures for storing business context
+ * about database schemas, including:
+ *
+ * - **TableDescription**: Business context for tables and columns
+ * - **TableRelationship**: Graph edges representing table relationships (FK, implicit, manual)
+ * - **QueryExample**: Verified SQL patterns with intent
+ * - **BusinessRule**: Domain constraints and conventions
+ * - **BusinessTerm**: Glossary entries for natural language → SQL translation
+ *
+ * ## Knowledge Graph Architecture
+ *
+ * The Knowledge Store is designed to evolve into a Knowledge Graph:
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │                     Knowledge Graph                             │
+ * │                                                                 │
+ * │   [Table A] ──JOINS_WITH──> [Table B] ──JOINS_WITH──> [Table C]│
+ * │       │                         │                               │
+ * │       │                         │                               │
+ * │   [Description]             [Description]                       │
+ * │   [Rules]                   [Rules]                             │
+ * │   [Examples]                [Terms]                             │
+ * │                                                                 │
+ * └─────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Multi-Database Support
+ *
+ * All references use `TableRef` which includes optional database identifier,
+ * enabling future cross-database relationship tracking.
+ *
+ * @module knowledge/types
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateId = generateId;
 exports.createKnowledgeMeta = createKnowledgeMeta;
+exports.createTableRef = createTableRef;
+exports.tableRefToString = tableRefToString;
+exports.tableRefsEqual = tableRefsEqual;
+exports.createRelationshipFromFK = createRelationshipFromFK;
+// ============================================================
+// Factory Functions
+// ============================================================
 /** Generate a unique ID */
 function generateId() {
     return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
@@ -24,4 +65,100 @@ function createKnowledgeMeta(source, schemaHash, owner) {
         owner,
     };
 }
+/**
+ * Create a TableRef from table name and optional schema/database.
+ *
+ * @param table - Table name
+ * @param schema - Schema name (defaults to 'public')
+ * @param database - Database name (optional)
+ * @returns TableRef object
+ *
+ * @example
+ * ```typescript
+ * const ref = createTableRef('users');
+ * // { schema: 'public', table: 'users' }
+ *
+ * const ref2 = createTableRef('orders', 'sales', 'analytics_db');
+ * // { database: 'analytics_db', schema: 'sales', table: 'orders' }
+ * ```
+ */
+function createTableRef(table, schema = 'public', database) {
+    const ref = { schema, table };
+    if (database) {
+        ref.database = database;
+    }
+    return ref;
+}
+/**
+ * Convert TableRef to a fully qualified string representation.
+ *
+ * @param ref - TableRef to stringify
+ * @returns String like "database.schema.table" or "schema.table"
+ *
+ * @example
+ * ```typescript
+ * tableRefToString({ schema: 'public', table: 'users' })
+ * // "public.users"
+ *
+ * tableRefToString({ database: 'analytics', schema: 'public', table: 'events' })
+ * // "analytics.public.events"
+ * ```
+ */
+function tableRefToString(ref) {
+    if (ref.database) {
+        return `${ref.database}.${ref.schema}.${ref.table}`;
+    }
+    return `${ref.schema}.${ref.table}`;
+}
+/**
+ * Check if two TableRefs refer to the same table.
+ *
+ * @param a - First TableRef
+ * @param b - Second TableRef
+ * @returns true if they refer to the same table
+ */
+function tableRefsEqual(a, b) {
+    return (a.table === b.table &&
+        a.schema === b.schema &&
+        (a.database ?? '') === (b.database ?? ''));
+}
+/**
+ * Create a TableRelationship from foreign key information.
+ *
+ * This is the standard way to create relationships from harvested FK data.
+ *
+ * @param params - Relationship parameters
+ * @returns Complete TableRelationship object
+ *
+ * @example
+ * ```typescript
+ * const relationship = createRelationshipFromFK({
+ *   fromTable: 'orders',
+ *   fromSchema: 'public',
+ *   fromColumn: 'user_id',
+ *   toTable: 'users',
+ *   toSchema: 'public',
+ *   toColumn: 'id',
+ *   constraintName: 'orders_user_id_fkey',
+ *   schemaHash: 'abc123',
+ * });
+ * ```
+ */
+function createRelationshipFromFK(params) {
+    const fromSchema = params.fromSchema ?? 'public';
+    const toSchema = params.toSchema ?? 'public';
+    return {
+        ...createKnowledgeMeta('auto', params.schemaHash),
+        type: 'table_relationship',
+        from: createTableRef(params.fromTable, fromSchema, params.database),
+        to: createTableRef(params.toTable, toSchema, params.database),
+        relationshipType: 'foreign_key',
+        joinCondition: `${params.fromTable}.${params.fromColumn} = ${params.toTable}.${params.toColumn}`,
+        cardinality: 'many-to-one', // Default for FK
+        fromColumns: [params.fromColumn],
+        toColumns: [params.toColumn],
+        isPreferred: true,
+        constraintName: params.constraintName,
+    };
+}
 //# sourceMappingURL=types.js.map

package/dist/knowledge/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/knowledge/types.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AA6JH,gCAEC;AAGD,kDAgBC;AAtBD,2BAA2B;AAC3B,SAAgB,UAAU;IACxB,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC;AAED,qDAAqD;AACrD,SAAgB,mBAAmB,CACjC,MAAuB,EACvB,UAAkB,EAClB,KAAc;IAEd,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO;QACL,EAAE,EAAE,UAAU,EAAE;QAChB,MAAM;QACN,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;QACzC,UAAU;QACV,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,GAAG;QACd,cAAc,EAAE,GAAG;QACnB,KAAK;KACN,CAAC;AACJ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/knowledge/types.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;IAExB,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,EAAE,CA8SpC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAuClB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;IAExB,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,EAAE,CA8VpC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CA8ClB"}