@hyperfixi/patterns-reference 2.0.0

package/src/semantic-bridge.ts

@@ -0,0 +1,204 @@
+/**
+ * Semantic Bridge
+ *
+ * Connects the patterns-reference database to the semantic registry,
+ * enabling runtime pattern matching using database-backed patterns.
+ *
+ * @example
+ * ```typescript
+ * import { initializeSemanticIntegration } from '@hyperfixi/patterns-reference';
+ *
+ * // Initialize integration with semantic parser
+ * await initializeSemanticIntegration();
+ *
+ * // Now the semantic parser can access patterns from the database
+ * import { parse } from '@lokascript/semantic';
+ * const result = parse('toggle .active', 'en');
+ * ```
+ *
+ * @module @hyperfixi/patterns-reference/semantic-bridge
+ */
+
+import {
+  createPatternsProvider,
+  type DatabasePatternsProvider,
+} from './registry/patterns-provider';
+import type { ConnectionOptions } from './types';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for semantic integration initialization.
+ */
+export interface SemanticIntegrationOptions extends ConnectionOptions {
+  /** Whether to register as the default provider */
+  registerAsDefault?: boolean;
+  /** Custom provider instance to use */
+  provider?: DatabasePatternsProvider;
+}
+
+/**
+ * Result of initialization.
+ */
+export interface IntegrationResult {
+  success: boolean;
+  provider: DatabasePatternsProvider;
+  registeredWith: 'semantic' | 'standalone';
+  error?: string;
+}
+
+// =============================================================================
+// Bridge State
+// =============================================================================
+
+let bridgeInitialized = false;
+let bridgeProvider: DatabasePatternsProvider | null = null;
+
+// =============================================================================
+// Integration Functions
+// =============================================================================
+
+/**
+ * Initialize semantic integration.
+ *
+ * This registers the patterns-reference database as an external pattern source
+ * with the @lokascript/semantic registry, enabling runtime pattern matching.
+ *
+ * @param options - Integration options
+ * @returns Integration result
+ *
+ * @example
+ * ```typescript
+ * const result = await initializeSemanticIntegration();
+ * if (result.success) {
+ *   console.log('Patterns available in semantic parser');
+ * }
+ * ```
+ */
+export async function initializeSemanticIntegration(
+  options?: SemanticIntegrationOptions
+): Promise<IntegrationResult> {
+  // Create or use provided provider
+  const provider = options?.provider || createPatternsProvider(options);
+  bridgeProvider = provider;
+
+  try {
+    // Try to register with @lokascript/semantic
+    // Use 'any' to avoid type errors with dynamic imports
+    const semantic = (await import('@lokascript/semantic')) as any;
+
+    if (typeof semantic.registerPatternsSource === 'function') {
+      semantic.registerPatternsSource(provider);
+      bridgeInitialized = true;
+
+      return {
+        success: true,
+        provider,
+        registeredWith: 'semantic',
+      };
+    } else {
+      // Semantic package doesn't have registerPatternsSource yet
+      console.warn(
+        '[SemanticBridge] @lokascript/semantic does not export registerPatternsSource. ' +
+          'Running in standalone mode.'
+      );
+
+      return {
+        success: true,
+        provider,
+        registeredWith: 'standalone',
+      };
+    }
+  } catch (error) {
+    // @lokascript/semantic not available
+    console.warn(
+      '[SemanticBridge] @lokascript/semantic not available:',
+      error instanceof Error ? error.message : String(error)
+    );
+
+    return {
+      success: true,
+      provider,
+      registeredWith: 'standalone',
+      error: '@lokascript/semantic not available',
+    };
+  }
+}
+
+/**
+ * Check if semantic integration is initialized.
+ */
+export function isSemanticIntegrationInitialized(): boolean {
+  return bridgeInitialized;
+}
+
+/**
+ * Get the bridge provider instance.
+ */
+export function getBridgeProvider(): DatabasePatternsProvider | null {
+  return bridgeProvider;
+}
+
+/**
+ * Uninitialize semantic integration.
+ * Useful for testing or cleanup.
+ */
+export async function uninitializeSemanticIntegration(): Promise<void> {
+  if (!bridgeProvider) {
+    return;
+  }
+
+  try {
+    const semantic = (await import('@lokascript/semantic')) as any;
+
+    if (typeof semantic.unregisterPatternsSource === 'function') {
+      semantic.unregisterPatternsSource(bridgeProvider.id);
+    }
+  } catch {
+    // Ignore errors during cleanup
+  }
+
+  bridgeProvider.clearCache();
+  bridgeProvider = null;
+  bridgeInitialized = false;
+}
+
+// =============================================================================
+// Convenience Functions
+// =============================================================================
+
+/**
+ * Query patterns from the database for a specific language.
+ * Works regardless of whether semantic integration is initialized.
+ *
+ * @param language - Language code
+ * @returns Array of pattern entries
+ */
+export async function queryPatterns(language: string) {
+  const provider = bridgeProvider || createPatternsProvider();
+  return provider.getPatternsForLanguage(language);
+}
+
+/**
+ * Query patterns from the database for a specific command.
+ *
+ * @param command - Command name (e.g., 'toggle', 'add')
+ * @param language - Optional language filter
+ * @returns Array of pattern entries
+ */
+export async function queryPatternsForCommand(command: string, language?: string) {
+  const provider = bridgeProvider || createPatternsProvider();
+  return provider.getPatternsForCommand(command, language);
+}
+
+/**
+ * Get supported languages from the database.
+ *
+ * @returns Array of language codes
+ */
+export async function getSupportedLanguages(): Promise<string[]> {
+  const provider = bridgeProvider || createPatternsProvider();
+  return provider.getSupportedLanguages();
+}

package/src/sync/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Sync Module
+ *
+ * Re-exports sync operations that were migrated from packages/semantic/scripts/.
+ * These are typically run via CLI scripts rather than imported directly.
+ */
+
+// Note: The actual sync implementations remain in packages/semantic/scripts/
+// for now, as they are Bun-specific and need direct database access.
+// This module provides type-safe wrappers that can be used programmatically.
+
+import type {
+  SyncOptions,
+  SyncResult,
+  ValidationOptions,
+  ValidationResult,
+  DiscoveryResult,
+} from '../types';
+
+export type { SyncOptions, SyncResult, ValidationOptions, ValidationResult, DiscoveryResult };
+
+/**
+ * Sync translations from code_examples to pattern_translations.
+ *
+ * This is a placeholder - the actual implementation is in
+ * packages/semantic/scripts/sync-lsp-translations.ts
+ */
+export async function syncTranslations(_options: SyncOptions = {}): Promise<SyncResult> {
+  throw new Error(
+    'syncTranslations should be run via: bun run packages/semantic/scripts/sync-lsp-translations.ts'
+  );
+}
+
+/**
+ * Validate all translations in the database.
+ *
+ * This is a placeholder - the actual implementation is in
+ * packages/semantic/scripts/validate-translations.ts
+ */
+export async function validateAllTranslations(
+  _options: ValidationOptions = {}
+): Promise<ValidationResult> {
+  throw new Error(
+    'validateAllTranslations should be run via: bun run packages/semantic/scripts/validate-translations.ts'
+  );
+}
+
+/**
+ * Discover and analyze patterns in the database.
+ *
+ * This is a placeholder - the actual implementation is in
+ * packages/semantic/scripts/pattern-discovery.ts
+ */
+export async function discoverPatterns(_verbose: boolean = false): Promise<DiscoveryResult> {
+  throw new Error(
+    'discoverPatterns should be run via: bun run packages/semantic/scripts/pattern-discovery.ts'
+  );
+}
+
+/**
+ * Seed LLM examples from verified translations.
+ *
+ * This is a placeholder - the actual implementation is in
+ * packages/semantic/scripts/seed-llm-examples.ts
+ */
+export async function seedLLMExamples(_dryRun: boolean = false): Promise<{ count: number }> {
+  throw new Error(
+    'seedLLMExamples should be run via: bun run packages/semantic/scripts/seed-llm-examples.ts'
+  );
+}

package/src/types/better-sqlite3.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Type declarations for better-sqlite3.
+ * This is a minimal declaration to support typecheck before npm install.
+ * The full types from @types/better-sqlite3 will be used after install.
+ */
+
+declare module 'better-sqlite3' {
+  namespace BetterSqlite3 {
+    interface Database {
+      prepare<T = unknown>(sql: string): Statement<T>;
+      exec(sql: string): this;
+      pragma(pragma: string, options?: { simple?: boolean }): unknown;
+      close(): void;
+    }
+
+    interface Statement<T = unknown> {
+      run(...params: unknown[]): RunResult;
+      get(...params: unknown[]): T | undefined;
+      all(...params: unknown[]): T[];
+    }
+
+    interface RunResult {
+      changes: number;
+      lastInsertRowid: number | bigint;
+    }
+
+    interface Options {
+      readonly?: boolean;
+      fileMustExist?: boolean;
+      timeout?: number;
+      verbose?: (message?: unknown, ...additionalArgs: unknown[]) => void;
+    }
+  }
+
+  class Database implements BetterSqlite3.Database {
+    constructor(filename: string, options?: BetterSqlite3.Options);
+    prepare<T = unknown>(sql: string): BetterSqlite3.Statement<T>;
+    exec(sql: string): this;
+    pragma(pragma: string, options?: { simple?: boolean }): unknown;
+    close(): void;
+  }
+
+  export = Database;
+}