@hyperfixi/patterns-reference 2.0.0

package/README.md

@@ -0,0 +1,311 @@
+# @hyperfixi/patterns-reference
+
+Queryable patterns database for hyperscript with multilingual translations and LLM few-shot learning support.
+
+## Installation
+
+```bash
+npm install @hyperfixi/patterns-reference
+```
+
+## Quick Start
+
+The package ships with a **pre-populated SQLite database** containing:
+
+- 106 code examples covering hyperscript commands and real-world UI patterns
+- 1,378 translations (106 patterns × 13 languages)
+- 414 LLM few-shot examples for code generation
+
+No setup required - just install and use:
+
+### Use the API
+
+```typescript
+import { createPatternsReference } from '@hyperfixi/patterns-reference';
+
+// Create a patterns reference instance
+const ref = createPatternsReference({
+  dbPath: './data/patterns.db',
+  readonly: true,
+});
+
+// Query patterns
+const pattern = await ref.getPatternById('toggle-class-basic');
+console.log(pattern?.rawCode); // 'on click toggle .active'
+
+// Search patterns
+const results = await ref.searchPatterns('toggle');
+
+// Get LLM examples for few-shot learning
+const examples = await ref.getLLMExamples('toggle a class on click');
+
+// Get statistics
+const stats = await ref.getStats();
+console.log(`Total patterns: ${stats.totalPatterns}`);
+
+// Clean up
+ref.close();
+```
+
+## API Reference
+
+### Pattern Queries
+
+```typescript
+// Get pattern by ID
+getPatternById(id: string): Promise<Pattern | null>
+
+// Get patterns by category (e.g., 'class-manipulation', 'visibility')
+getPatternsByCategory(category: string): Promise<Pattern[]>
+
+// Get patterns containing a specific command
+getPatternsByCommand(command: string): Promise<Pattern[]>
+
+// Full-text search across title, code, and description
+searchPatterns(query: string, options?: SearchOptions): Promise<Pattern[]>
+
+// Get all patterns (paginated)
+getAllPatterns(options?: SearchOptions): Promise<Pattern[]>
+
+// Get pattern statistics
+getPatternStats(): Promise<PatternStats>
+```
+
+### Translations
+
+```typescript
+// Get translation for a specific language
+getTranslation(patternId: string, language: string): Promise<Translation | null>
+
+// Get all translations for a pattern
+getAllTranslations(patternId: string): Promise<Translation[]>
+
+// Verify a translation parses correctly
+verifyTranslation(translation: Translation): Promise<VerificationResult>
+```
+
+### LLM Support
+
+```typescript
+// Get examples matching a prompt (for few-shot learning)
+getLLMExamples(prompt: string, language?: string, limit?: number): Promise<LLMExample[]>
+
+// Get examples by command type
+getExamplesByCommand(command: string, language?: string, limit?: number): Promise<LLMExample[]>
+
+// Get high-quality examples
+getHighQualityExamples(language?: string, minQuality?: number, limit?: number): Promise<LLMExample[]>
+
+// Build formatted context for LLM prompting
+buildFewShotContext(prompt: string, language?: string, numExamples?: number): Promise<string>
+
+// Get LLM example statistics
+getLLMStats(): Promise<{ total: number; byLanguage: Record<string, number>; avgQuality: number; totalUsage: number }>
+```
+
+## Configuration
+
+### Database Path
+
+The database path can be configured via:
+
+1. **Constructor option:**
+
+   ```typescript
+   createPatternsReference({ dbPath: '/path/to/db.sqlite' });
+   ```
+
+2. **Environment variables:**
+
+   ```bash
+   export LSP_DB_PATH="/path/to/db.sqlite"
+   # or
+   export HYPERSCRIPT_LSP_DB="/path/to/db.sqlite"
+   ```
+
+### Scripts (Development Only)
+
+These scripts are for contributors regenerating the database. **End users don't need these** - the database ships pre-populated.
+
+| Script                      | Description                                              |
+| --------------------------- | -------------------------------------------------------- |
+| `npm run populate`          | Full database setup (init + translations + LLM examples) |
+| `npm run db:init`           | Initialize database with seed patterns                   |
+| `npm run db:init:force`     | Reinitialize database (overwrites existing)              |
+| `npm run sync:translations` | Generate translations for all 13 languages               |
+| `npm run seed:llm`          | Generate LLM few-shot examples                           |
+| `npm run validate`          | Validate all patterns parse correctly                    |
+| `npm run validate:fix`      | Validate and update verified_parses flag                 |
+| `npm run build`             | Build the package                                        |
+| `npm test`                  | Run tests in watch mode                                  |
+| `npm run test:run`          | Run tests once                                           |
+
+## Database Schema
+
+### code_examples
+
+Pattern source code from the hyperscript cookbook.
+
+| Column      | Type | Description                           |
+| ----------- | ---- | ------------------------------------- |
+| id          | TEXT | Unique identifier                     |
+| title       | TEXT | Human-readable title                  |
+| raw_code    | TEXT | Hyperscript code                      |
+| description | TEXT | Pattern description                   |
+| feature     | TEXT | Category (e.g., 'class-manipulation') |
+| created_at  | TEXT | Creation timestamp                    |
+
+### pattern_translations
+
+Multilingual translations of patterns.
+
+| Column          | Type    | Description                      |
+| --------------- | ------- | -------------------------------- |
+| id              | INTEGER | Auto-increment ID                |
+| code_example_id | TEXT    | Foreign key to code_examples     |
+| language        | TEXT    | Language code (en, ja, es, etc.) |
+| hyperscript     | TEXT    | Translated code                  |
+| word_order      | TEXT    | SVO, SOV, VSO, or V2             |
+| confidence      | REAL    | Translation confidence (0-1)     |
+| verified_parses | INTEGER | Whether translation parses (0/1) |
+
+### llm_examples
+
+Prompt/completion pairs for few-shot learning.
+
+| Column          | Type    | Description                  |
+| --------------- | ------- | ---------------------------- |
+| id              | INTEGER | Auto-increment ID            |
+| code_example_id | TEXT    | Foreign key to code_examples |
+| language        | TEXT    | Language code                |
+| prompt          | TEXT    | Natural language prompt      |
+| completion      | TEXT    | Hyperscript code             |
+| quality_score   | REAL    | Quality rating (0-1)         |
+| usage_count     | INTEGER | Retrieval count              |
+
+## Supported Languages
+
+The database supports 13 languages with different word orders:
+
+| Language   | Code | Word Order |
+| ---------- | ---- | ---------- |
+| English    | en   | SVO        |
+| Spanish    | es   | SVO        |
+| French     | fr   | SVO        |
+| Portuguese | pt   | SVO        |
+| Indonesian | id   | SVO        |
+| Swahili    | sw   | SVO        |
+| Chinese    | zh   | SVO        |
+| Japanese   | ja   | SOV        |
+| Korean     | ko   | SOV        |
+| Turkish    | tr   | SOV        |
+| Quechua    | qu   | SOV        |
+| Arabic     | ar   | VSO        |
+| German     | de   | V2         |
+
+## Integration with @lokascript/semantic
+
+The patterns-reference package integrates with @lokascript/semantic to provide runtime pattern matching from the database.
+
+### Semantic Bridge
+
+```typescript
+import { initializeSemanticIntegration } from '@hyperfixi/patterns-reference';
+
+// Initialize integration (registers database as pattern source)
+const result = await initializeSemanticIntegration();
+
+if (result.success) {
+  console.log(`Registered with: ${result.registeredWith}`);
+  // 'semantic' if @lokascript/semantic is available
+  // 'standalone' if running without semantic package
+}
+
+// Query patterns directly
+import { queryPatterns, getSupportedLanguages } from '@hyperfixi/patterns-reference';
+
+const jaPatterns = await queryPatterns('ja');
+const languages = await getSupportedLanguages();
+```
+
+### LLM Adapter (for @lokascript/core)
+
+The package provides a unified LLM adapter that replaces the deprecated `llm-examples-query.ts`:
+
+```typescript
+import { findRelevantExamples, buildFewShotContextSync } from '@hyperfixi/patterns-reference';
+
+// Find examples matching a prompt
+const examples = findRelevantExamples('toggle a class on click', 'en', 5);
+
+// Build formatted context for LLM prompting
+const context = buildFewShotContextSync('show a modal', 'en', 3);
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Full database setup
+npm run populate
+
+# Run tests
+npm test
+
+# Validate translations
+npm run validate
+
+# Build
+npm run build
+```
+
+## Troubleshooting
+
+### Native Module Installation
+
+This package uses `better-sqlite3`, a native Node.js module. If you encounter installation errors:
+
+**macOS:**
+
+```bash
+xcode-select --install  # Install Xcode command line tools
+```
+
+**Linux (Debian/Ubuntu):**
+
+```bash
+sudo apt-get install build-essential python3
+```
+
+**Windows:**
+
+```bash
+npm install --global windows-build-tools
+```
+
+`better-sqlite3` ships with prebuilt binaries for most platforms, so compilation is usually not required. If you encounter issues, ensure you're using a supported Node.js version (18, 20, or 22 LTS).
+
+### Database Not Found
+
+If you get "database not found" errors, the database path may not be resolving correctly. Set it explicitly:
+
+```typescript
+import { createPatternsReference } from '@hyperfixi/patterns-reference';
+import { join } from 'path';
+
+const ref = createPatternsReference({
+  dbPath: join(__dirname, 'node_modules/@hyperfixi/patterns-reference/data/patterns.db'),
+});
+```
+
+Or use environment variables:
+
+```bash
+export LSP_DB_PATH="/absolute/path/to/patterns.db"
+```
+
+## License
+
+MIT

package/data/hyperfixi-extensions.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "./hyperfixi-extensions.schema.json",
+  "version": "1.0.0",
+  "lastUpdated": "2026-01-19",
+  "description": "Tracks HyperFixi-specific syntax extensions that may not be available in official _hyperscript",
+  "extensions": [
+    {
+      "id": "possessive-dot-notation",
+      "name": "Possessive Dot Notation",
+      "description": "JavaScript-style dot notation with possessive pronouns (my.value, its.value, your.value)",
+      "status": "stable",
+      "addedVersion": "1.0.0",
+      "officialHyperscript": false,
+      "syntax": {
+        "hyperfixi": ["my.property", "its.property", "your.property", "my?.property"],
+        "standard": ["my property", "its property", "your property"],
+        "equivalent": ["me.property", "it.property", "you.property", "me?.property"]
+      },
+      "examples": [
+        {
+          "hyperfixi": "set my.textContent to \"Done!\"",
+          "standard": "set my textContent to \"Done!\"",
+          "description": "Set element text content"
+        },
+        {
+          "hyperfixi": "put my.value.toUpperCase() into #preview",
+          "standard": null,
+          "description": "Method chaining on property access"
+        },
+        {
+          "hyperfixi": "log my?.dataset?.customValue",
+          "standard": null,
+          "description": "Optional chaining for safe access"
+        }
+      ],
+      "testFile": "packages/core/src/parser/possessive-dot-notation.test.ts",
+      "documentationFile": "packages/core/docs/EXTENSIONS.md"
+    },
+    {
+      "id": "multilingual-keywords",
+      "name": "Multilingual Keyword Support",
+      "description": "Write hyperscript in 13 languages with automatic grammar transformation",
+      "status": "stable",
+      "addedVersion": "1.0.0",
+      "officialHyperscript": false,
+      "supportedLanguages": [
+        "en",
+        "es",
+        "fr",
+        "pt",
+        "de",
+        "ja",
+        "ko",
+        "zh",
+        "ar",
+        "tr",
+        "id",
+        "sw",
+        "qu"
+      ],
+      "examples": [
+        {
+          "hyperfixi": "クリック で .active を 切り替え",
+          "standard": "on click toggle .active",
+          "description": "Japanese (SOV word order)"
+        },
+        {
+          "hyperfixi": "en clic alternar .active",
+          "standard": "on click toggle .active",
+          "description": "Spanish"
+        }
+      ],
+      "documentationFile": "packages/semantic/README.md"
+    },
+    {
+      "id": "enhanced-type-conversion",
+      "name": "Enhanced Type Conversion",
+      "description": "Extended 'as' keyword support for additional types",
+      "status": "stable",
+      "addedVersion": "1.0.0",
+      "officialHyperscript": "partial",
+      "additionalTypes": ["FormData", "JSON", "Object", "Date"],
+      "examples": [
+        {
+          "hyperfixi": "form as FormData",
+          "standard": null,
+          "description": "Convert form element to FormData"
+        },
+        {
+          "hyperfixi": "obj as JSON",
+          "standard": null,
+          "description": "Serialize object to JSON string"
+        }
+      ]
+    }
+  ],
+  "compatibilityNotes": {
+    "overallCompatibility": "~85%",
+    "testedAgainst": "hyperscript.org v0.9.x",
+    "knownDifferences": [
+      "HyperFixi extensions are additive - standard _hyperscript syntax always works",
+      "Some edge cases in event handling may differ",
+      "Behavior definitions have minor syntax variations"
+    ]
+  }
+}

package/dist/api/index.d.mts

@@ -0,0 +1,59 @@
+export { r as addLLMExample, q as buildFewShotContext, c as getAllPatterns, f as getAllTranslations, n as getExamplesByCommand, j as getHighConfidenceTranslations, o as getHighQualityExamples, m as getLLMExamples, t as getLLMStats, p as getMostUsedExamples, g as getPatternById, d as getPatternStats, a as getPatternsByCategory, b as getPatternsByCommand, e as getTranslation, k as getTranslationStats, h as getTranslationsByLanguage, i as getVerifiedTranslations, l as getWordOrder, s as searchPatterns, u as updateQualityScore, v as verifyTranslation } from '../llm-UOOBXwj3.mjs';
+import { C as ConnectionOptions, r as PatternRole, e as Pattern, R as RoleType } from '../index-CBoczxz7.mjs';
+import { SemanticRole } from '@lokascript/semantic';
+
+/**
+ * Pattern Roles API
+ *
+ * Provides functions to query semantic roles extracted from patterns.
+ */
+
+/**
+ * Get all semantic roles for a pattern.
+ */
+declare function getPatternRoles(patternId: string, options?: ConnectionOptions): Promise<PatternRole[]>;
+/**
+ * Get all patterns that contain a specific semantic role.
+ */
+declare function getPatternsByRole(role: SemanticRole, options?: ConnectionOptions): Promise<Pattern[]>;
+/**
+ * Get patterns that contain all specified roles.
+ */
+declare function getPatternsByRoles(roles: SemanticRole[], matchMode?: 'all' | 'any', options?: ConnectionOptions): Promise<Pattern[]>;
+/**
+ * Get patterns by role value (e.g., all patterns that target ".active").
+ */
+declare function getPatternsByRoleValue(role: SemanticRole, value: string, options?: ConnectionOptions): Promise<Pattern[]>;
+/**
+ * Get statistics about role usage across all patterns.
+ */
+declare function getRoleStats(options?: ConnectionOptions): Promise<{
+    totalRoles: number;
+    byRole: Record<SemanticRole, number>;
+    byRoleType: Record<RoleType, number>;
+    topRoleValues: Array<{
+        role: SemanticRole;
+        value: string;
+        count: number;
+    }>;
+    patternsWithRoles: number;
+    patternsWithoutRoles: number;
+}>;
+/**
+ * Get role distribution for a specific command.
+ */
+declare function getRolesByCommand(command: string, options?: ConnectionOptions): Promise<Record<SemanticRole, number>>;
+/**
+ * Insert a pattern role into the database.
+ */
+declare function insertPatternRole(role: Omit<PatternRole, 'id'>, options?: ConnectionOptions): Promise<number>;
+/**
+ * Delete all roles for a pattern.
+ */
+declare function deletePatternRoles(patternId: string, options?: ConnectionOptions): Promise<number>;
+/**
+ * Delete all roles from the database.
+ */
+declare function clearAllRoles(options?: ConnectionOptions): Promise<number>;
+
+export { clearAllRoles, deletePatternRoles, getPatternRoles, getPatternsByRole, getPatternsByRoleValue, getPatternsByRoles, getRoleStats, getRolesByCommand, insertPatternRole };

package/dist/api/index.d.ts

@@ -0,0 +1,59 @@
+export { r as addLLMExample, q as buildFewShotContext, c as getAllPatterns, f as getAllTranslations, n as getExamplesByCommand, j as getHighConfidenceTranslations, o as getHighQualityExamples, m as getLLMExamples, t as getLLMStats, p as getMostUsedExamples, g as getPatternById, d as getPatternStats, a as getPatternsByCategory, b as getPatternsByCommand, e as getTranslation, k as getTranslationStats, h as getTranslationsByLanguage, i as getVerifiedTranslations, l as getWordOrder, s as searchPatterns, u as updateQualityScore, v as verifyTranslation } from '../llm-DMR6tmkM.js';
+import { C as ConnectionOptions, r as PatternRole, e as Pattern, R as RoleType } from '../index-CBoczxz7.js';
+import { SemanticRole } from '@lokascript/semantic';
+
+/**
+ * Pattern Roles API
+ *
+ * Provides functions to query semantic roles extracted from patterns.
+ */
+
+/**
+ * Get all semantic roles for a pattern.
+ */
+declare function getPatternRoles(patternId: string, options?: ConnectionOptions): Promise<PatternRole[]>;
+/**
+ * Get all patterns that contain a specific semantic role.
+ */
+declare function getPatternsByRole(role: SemanticRole, options?: ConnectionOptions): Promise<Pattern[]>;
+/**
+ * Get patterns that contain all specified roles.
+ */
+declare function getPatternsByRoles(roles: SemanticRole[], matchMode?: 'all' | 'any', options?: ConnectionOptions): Promise<Pattern[]>;
+/**
+ * Get patterns by role value (e.g., all patterns that target ".active").
+ */
+declare function getPatternsByRoleValue(role: SemanticRole, value: string, options?: ConnectionOptions): Promise<Pattern[]>;
+/**
+ * Get statistics about role usage across all patterns.
+ */
+declare function getRoleStats(options?: ConnectionOptions): Promise<{
+    totalRoles: number;
+    byRole: Record<SemanticRole, number>;
+    byRoleType: Record<RoleType, number>;
+    topRoleValues: Array<{
+        role: SemanticRole;
+        value: string;
+        count: number;
+    }>;
+    patternsWithRoles: number;
+    patternsWithoutRoles: number;
+}>;
+/**
+ * Get role distribution for a specific command.
+ */
+declare function getRolesByCommand(command: string, options?: ConnectionOptions): Promise<Record<SemanticRole, number>>;
+/**
+ * Insert a pattern role into the database.
+ */
+declare function insertPatternRole(role: Omit<PatternRole, 'id'>, options?: ConnectionOptions): Promise<number>;
+/**
+ * Delete all roles for a pattern.
+ */
+declare function deletePatternRoles(patternId: string, options?: ConnectionOptions): Promise<number>;
+/**
+ * Delete all roles from the database.
+ */
+declare function clearAllRoles(options?: ConnectionOptions): Promise<number>;
+
+export { clearAllRoles, deletePatternRoles, getPatternRoles, getPatternsByRole, getPatternsByRoleValue, getPatternsByRoles, getRoleStats, getRolesByCommand, insertPatternRole };