@hyperfixi/patterns-reference 2.0.0

package/src/database/connection.ts

@@ -0,0 +1,85 @@
+/**
+ * Database Connection Management
+ *
+ * Provides singleton connection to the patterns-reference SQLite database.
+ */
+
+import Database from 'better-sqlite3';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import type { ConnectionOptions } from '../types';
+
+// Resolve __dirname for ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Default path resolved from the dist directory after bundling
+// When bundled by tsup, __dirname will be the dist/ folder
+// So we need to go up one level to reach the package root, then into data/
+const DEFAULT_DB_PATH =
+  process.env.LSP_DB_PATH ||
+  process.env.HYPERSCRIPT_LSP_DB ||
+  join(__dirname, '../data/patterns.db');
+
+let dbInstance: InstanceType<typeof Database> | null = null;
+let currentDbPath: string | null = null;
+
+/**
+ * Get database connection (lazy singleton).
+ */
+export function getDatabase(options: ConnectionOptions = {}): InstanceType<typeof Database> {
+  const dbPath = options.dbPath ?? DEFAULT_DB_PATH;
+
+  // Return existing connection if same path
+  if (dbInstance !== null && currentDbPath === dbPath) {
+    return dbInstance;
+  }
+
+  // Close existing connection if path changed
+  if (dbInstance !== null) {
+    dbInstance.close();
+  }
+
+  dbInstance = new Database(dbPath, {
+    readonly: options.readonly ?? false,
+  });
+
+  // Enable foreign keys
+  dbInstance.pragma('foreign_keys = ON');
+
+  currentDbPath = dbPath;
+  return dbInstance;
+}
+
+/**
+ * Close database connection.
+ */
+export function closeDatabase(): void {
+  if (dbInstance) {
+    dbInstance.close();
+    dbInstance = null;
+    currentDbPath = null;
+  }
+}
+
+/**
+ * For testing: reset the database connection.
+ */
+export function resetConnection(): void {
+  dbInstance = null;
+  currentDbPath = null;
+}
+
+/**
+ * Check if database is connected.
+ */
+export function isConnected(): boolean {
+  return dbInstance !== null;
+}
+
+/**
+ * Get the current database path.
+ */
+export function getCurrentDbPath(): string | null {
+  return currentDbPath;
+}

package/src/index.ts

@@ -0,0 +1,266 @@
+/**
+ * @hyperfixi/patterns-reference
+ *
+ * Queryable patterns database for hyperscript with multilingual translations
+ * and LLM support for few-shot learning.
+ *
+ * @example
+ * ```typescript
+ * import { createPatternsReference } from '@hyperfixi/patterns-reference';
+ *
+ * const ref = createPatternsReference();
+ *
+ * // Query patterns
+ * const pattern = await ref.getPatternById('toggle-class-basic');
+ * const patterns = await ref.searchPatterns('toggle');
+ *
+ * // Get translations
+ * const translation = await ref.getTranslation('toggle-class-basic', 'ja');
+ *
+ * // Get LLM examples
+ * const examples = await ref.getLLMExamples('toggle a class on click');
+ *
+ * // Clean up
+ * ref.close();
+ * ```
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  // Pattern types
+  Pattern,
+  ClassifiedPattern,
+  ComplexityLevel,
+  EngineCompat,
+
+  // Translation types
+  Translation,
+  VerificationResult,
+  WordOrder,
+  TranslationMethod,
+
+  // LLM types
+  LLMExample,
+
+  // Language documentation types
+  Command,
+  Expression,
+  ExpressionOperator,
+  Keyword,
+  Feature,
+  SpecialSymbol,
+  LanguageElement,
+  LanguageElementType,
+  LanguageDocsStats,
+
+  // API types
+  PatternsReference,
+  SearchOptions,
+  TestOptions,
+  PatternStats,
+
+  // Sync types
+  SyncOptions,
+  SyncResult,
+  ValidationOptions,
+  ValidationResult,
+  DiscoveryResult,
+
+  // Connection types
+  ConnectionOptions,
+} from './types';
+
+// =============================================================================
+// Database
+// =============================================================================
+
+export {
+  getDatabase,
+  closeDatabase,
+  resetConnection,
+  isConnected,
+  getCurrentDbPath,
+} from './database/connection';
+
+// =============================================================================
+// API
+// =============================================================================
+
+// Patterns
+export {
+  getPatternById,
+  getPatternsByCategory,
+  getPatternsByCommand,
+  searchPatterns,
+  getAllPatterns,
+  getPatternStats,
+} from './api/patterns';
+
+// Translations
+export {
+  getTranslation,
+  getAllTranslations,
+  getTranslationsByLanguage,
+  getVerifiedTranslations,
+  getHighConfidenceTranslations,
+  verifyTranslation,
+  getTranslationStats,
+  getWordOrder,
+} from './api/translations';
+
+// LLM
+export {
+  getLLMExamples,
+  getExamplesByCommand,
+  getHighQualityExamples,
+  getMostUsedExamples,
+  buildFewShotContext,
+  addLLMExample,
+  updateQualityScore,
+  getLLMStats,
+} from './api/llm';
+
+// Language Documentation
+export {
+  // Commands
+  getCommandByName,
+  getAllCommands,
+  searchCommands,
+  // Expressions
+  getExpressionByName,
+  getAllExpressions,
+  getExpressionsByCategory,
+  // Keywords
+  getKeywordByName,
+  getAllKeywords,
+  // Features
+  getFeatureByName,
+  getAllFeatures,
+  // Special Symbols
+  getSpecialSymbolByName,
+  getAllSpecialSymbols,
+  // Unified search
+  searchLanguageElements,
+  // Statistics
+  getLanguageDocsStats,
+} from './api/language-docs';
+
+// =============================================================================
+// Sync (placeholders - run via CLI scripts)
+// =============================================================================
+
+export {
+  syncTranslations,
+  validateAllTranslations,
+  discoverPatterns,
+  seedLLMExamples,
+} from './sync';
+
+// =============================================================================
+// Adapters (for cross-package integration)
+// =============================================================================
+
+export {
+  // Unified adapter factory
+  createLLMAdapter,
+  // Sync interface (backward compat with packages/core/src/context/llm-examples-query.ts)
+  findRelevantExamples,
+  findExamplesByCommand,
+  buildFewShotContextSync,
+  trackExampleUsage,
+  getLLMExampleStats,
+  isDatabaseAvailable,
+  // Types
+  type LLMExampleRecord,
+} from './adapters/llm-adapter';
+
+// =============================================================================
+// Registry Integration (for @lokascript/semantic)
+// =============================================================================
+
+export {
+  // Patterns provider
+  DatabasePatternsProvider,
+  createPatternsProvider,
+  getDefaultProvider,
+  resetDefaultProvider,
+  // Types
+  type PatternsSource,
+  type PatternEntry,
+} from './registry/patterns-provider';
+
+// =============================================================================
+// Semantic Bridge
+// =============================================================================
+
+export {
+  // Initialization
+  initializeSemanticIntegration,
+  uninitializeSemanticIntegration,
+  isSemanticIntegrationInitialized,
+  getBridgeProvider,
+  // Query helpers
+  queryPatterns,
+  queryPatternsForCommand,
+  getSupportedLanguages,
+  // Types
+  type SemanticIntegrationOptions,
+  type IntegrationResult,
+} from './semantic-bridge';
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+import type { PatternsReference, ConnectionOptions } from './types';
+import * as patterns from './api/patterns';
+import * as translations from './api/translations';
+import * as llm from './api/llm';
+import { getDatabase, closeDatabase } from './database/connection';
+
+/**
+ * Create a PatternsReference instance.
+ *
+ * This provides a unified API for querying patterns, translations,
+ * and LLM examples from the hyperscript-lsp database.
+ *
+ * @param options - Connection options (dbPath, readonly)
+ * @returns PatternsReference instance
+ */
+export function createPatternsReference(options?: ConnectionOptions): PatternsReference {
+  // Initialize database connection
+  getDatabase(options);
+
+  return {
+    // Patterns
+    getPatternById: id => patterns.getPatternById(id, options),
+    getPatternsByCategory: category => patterns.getPatternsByCategory(category, options),
+    getPatternsByCommand: command => patterns.getPatternsByCommand(command, options),
+    searchPatterns: (query, searchOptions) =>
+      patterns.searchPatterns(query, searchOptions, options),
+
+    // Translations
+    getTranslation: (patternId, language) =>
+      translations.getTranslation(patternId, language, options),
+    getAllTranslations: patternId => translations.getAllTranslations(patternId, options),
+    verifyTranslation: translation => translations.verifyTranslation(translation, options),
+
+    // LLM
+    getLLMExamples: (prompt, language, limit) =>
+      llm.getLLMExamples(prompt, language, limit, options),
+
+    // Stats
+    getStats: () => patterns.getPatternStats(options),
+
+    // Connection
+    close: closeDatabase,
+  };
+}
+
+/**
+ * Version of the package.
+ */
+export const VERSION = '0.1.0';

package/src/registry/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Registry integration module.
+ *
+ * @module @hyperfixi/patterns-reference/registry
+ */
+
+export * from './patterns-provider';

package/src/registry/patterns-provider.ts

@@ -0,0 +1,250 @@
+/**
+ * Patterns Provider
+ *
+ * Provides patterns from the patterns-reference database to the semantic registry.
+ * This enables runtime pattern matching using database-backed patterns.
+ *
+ * @module @hyperfixi/patterns-reference/registry
+ */
+
+import { getDatabase } from '../database/connection';
+import type { Pattern, Translation, ConnectionOptions } from '../types';
+import { getPatternsByCommand, getAllPatterns } from '../api/patterns';
+import { getTranslationsByLanguage, getVerifiedTranslations } from '../api/translations';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Pattern source interface for external pattern providers.
+ */
+export interface PatternsSource {
+  /** Unique identifier for the source */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Get patterns for a specific language */
+  getPatternsForLanguage(language: string): Promise<PatternEntry[]>;
+  /** Get patterns for a specific command */
+  getPatternsForCommand(command: string, language?: string): Promise<PatternEntry[]>;
+  /** Check if source has patterns for a language */
+  hasPatterns(language: string): Promise<boolean>;
+  /** Get all supported languages */
+  getSupportedLanguages(): Promise<string[]>;
+}
+
+/**
+ * Pattern entry from the database.
+ */
+export interface PatternEntry {
+  /** Pattern ID */
+  id: string;
+  /** The hyperscript code */
+  code: string;
+  /** Primary command (toggle, add, remove, etc.) */
+  command: string | null;
+  /** Language code */
+  language: string;
+  /** Confidence score (0-1) */
+  confidence: number;
+  /** Whether the pattern has been verified to parse correctly */
+  verified: boolean;
+  /** Pattern title/description */
+  title?: string;
+  /** Pattern category */
+  category?: string;
+}
+
+// =============================================================================
+// Patterns Provider Implementation
+// =============================================================================
+
+/**
+ * Database-backed patterns provider.
+ */
+export class DatabasePatternsProvider implements PatternsSource {
+  public readonly id = 'patterns-reference-db';
+  public readonly name = 'Patterns Reference Database';
+
+  private options: ConnectionOptions;
+  private languageCache: Map<string, PatternEntry[]> = new Map();
+  private supportedLanguagesCache: string[] | null = null;
+
+  constructor(options?: ConnectionOptions) {
+    this.options = options || {};
+  }
+
+  /**
+   * Get patterns for a specific language.
+   */
+  async getPatternsForLanguage(language: string): Promise<PatternEntry[]> {
+    // Check cache
+    const cached = this.languageCache.get(language);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      // Get verified translations for this language
+      const translations = await getVerifiedTranslations(language, 1000, this.options);
+
+      const patterns: PatternEntry[] = translations.map(t => ({
+        id: t.codeExampleId,
+        code: t.hyperscript,
+        command: this.extractCommand(t.hyperscript),
+        language: t.language,
+        confidence: t.confidence,
+        verified: t.verifiedParses,
+      }));
+
+      this.languageCache.set(language, patterns);
+      return patterns;
+    } catch (error) {
+      console.warn(
+        `[PatternsProvider] Failed to get patterns for ${language}:`,
+        error instanceof Error ? error.message : String(error)
+      );
+      return [];
+    }
+  }
+
+  /**
+   * Get patterns for a specific command.
+   */
+  async getPatternsForCommand(command: string, language?: string): Promise<PatternEntry[]> {
+    try {
+      const patterns = await getPatternsByCommand(command, this.options);
+
+      const entries: PatternEntry[] = patterns.map(p => ({
+        id: p.id,
+        code: p.rawCode,
+        command: p.primaryCommand,
+        language: language || 'en',
+        confidence: 1.0,
+        verified: true,
+        title: p.title,
+        category: p.category || undefined,
+      }));
+
+      return entries;
+    } catch (error) {
+      console.warn(
+        `[PatternsProvider] Failed to get patterns for command ${command}:`,
+        error instanceof Error ? error.message : String(error)
+      );
+      return [];
+    }
+  }
+
+  /**
+   * Check if source has patterns for a language.
+   */
+  async hasPatterns(language: string): Promise<boolean> {
+    const patterns = await this.getPatternsForLanguage(language);
+    return patterns.length > 0;
+  }
+
+  /**
+   * Get all supported languages.
+   */
+  async getSupportedLanguages(): Promise<string[]> {
+    if (this.supportedLanguagesCache) {
+      return this.supportedLanguagesCache;
+    }
+
+    try {
+      const db = getDatabase({ ...this.options, readonly: true });
+      const result = db
+        .prepare(
+          `
+        SELECT DISTINCT language FROM pattern_translations
+        WHERE verified_parses = 1
+      `
+        )
+        .all() as { language: string }[];
+
+      this.supportedLanguagesCache = result.map(r => r.language);
+      return this.supportedLanguagesCache;
+    } catch (error) {
+      console.warn(
+        '[PatternsProvider] Failed to get supported languages:',
+        error instanceof Error ? error.message : String(error)
+      );
+      return [];
+    }
+  }
+
+  /**
+   * Clear the pattern cache.
+   */
+  clearCache(): void {
+    this.languageCache.clear();
+    this.supportedLanguagesCache = null;
+  }
+
+  /**
+   * Extract primary command from hyperscript code.
+   */
+  private extractCommand(code: string): string | null {
+    const match = code.match(/^(?:on\s+\w+\s+)?(\w+)/i);
+    if (match) {
+      const keyword = match[1].toLowerCase();
+      const commands = [
+        'toggle',
+        'add',
+        'remove',
+        'put',
+        'set',
+        'show',
+        'hide',
+        'wait',
+        'log',
+        'send',
+        'fetch',
+        'call',
+        'trigger',
+        'transition',
+        'increment',
+        'decrement',
+      ];
+      if (commands.includes(keyword)) {
+        return keyword;
+      }
+    }
+    return null;
+  }
+}
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+let defaultProvider: DatabasePatternsProvider | null = null;
+
+/**
+ * Get the default patterns provider instance.
+ */
+export function getDefaultProvider(options?: ConnectionOptions): DatabasePatternsProvider {
+  if (!defaultProvider) {
+    defaultProvider = new DatabasePatternsProvider(options);
+  }
+  return defaultProvider;
+}
+
+/**
+ * Create a new patterns provider instance.
+ */
+export function createPatternsProvider(options?: ConnectionOptions): DatabasePatternsProvider {
+  return new DatabasePatternsProvider(options);
+}
+
+/**
+ * Reset the default provider (for testing).
+ */
+export function resetDefaultProvider(): void {
+  if (defaultProvider) {
+    defaultProvider.clearCache();
+    defaultProvider = null;
+  }
+}