@hyperfixi/patterns-reference 2.0.0

package/src/api/roles.ts

@@ -0,0 +1,401 @@
+/**
+ * Pattern Roles API
+ *
+ * Provides functions to query semantic roles extracted from patterns.
+ */
+
+import { getDatabase } from '../database/connection';
+import type {
+  PatternRole,
+  SemanticRole,
+  RoleType,
+  ConnectionOptions,
+  Pattern,
+  EngineCompat,
+} from '../types';
+
+// =============================================================================
+// Database Row Types
+// =============================================================================
+
+interface PatternRoleRow {
+  id: number;
+  code_example_id: string;
+  command_index: number;
+  role: string;
+  role_value: string | null;
+  role_type: string | null;
+  required: number;
+}
+
+interface CodeExampleRow {
+  id: string;
+  title: string;
+  raw_code: string;
+  description: string | null;
+  feature: string | null;
+  engine: string | null;
+  created_at: string;
+}
+
+// =============================================================================
+// Role Queries
+// =============================================================================
+
+/**
+ * Get all semantic roles for a pattern.
+ */
+export async function getPatternRoles(
+  patternId: string,
+  options?: ConnectionOptions
+): Promise<PatternRole[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  const rows = db
+    .prepare(
+      `
+    SELECT id, code_example_id, command_index, role, role_value, role_type, required
+    FROM pattern_roles
+    WHERE code_example_id = ?
+    ORDER BY command_index, role
+  `
+    )
+    .all(patternId) as PatternRoleRow[];
+
+  return rows.map(mapRowToPatternRole);
+}
+
+/**
+ * Get all patterns that contain a specific semantic role.
+ */
+export async function getPatternsByRole(
+  role: SemanticRole,
+  options?: ConnectionOptions
+): Promise<Pattern[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  const rows = db
+    .prepare(
+      `
+    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+    FROM code_examples ce
+    INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
+    WHERE pr.role = ?
+    ORDER BY ce.title
+  `
+    )
+    .all(role) as CodeExampleRow[];
+
+  return rows.map(mapRowToPattern);
+}
+
+/**
+ * Get patterns that contain all specified roles.
+ */
+export async function getPatternsByRoles(
+  roles: SemanticRole[],
+  matchMode: 'all' | 'any' = 'any',
+  options?: ConnectionOptions
+): Promise<Pattern[]> {
+  if (roles.length === 0) return [];
+
+  const db = getDatabase({ ...options, readonly: true });
+
+  if (matchMode === 'any') {
+    // Match patterns with ANY of the specified roles
+    const placeholders = roles.map(() => '?').join(', ');
+    const rows = db
+      .prepare(
+        `
+      SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+      FROM code_examples ce
+      INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
+      WHERE pr.role IN (${placeholders})
+      ORDER BY ce.title
+    `
+      )
+      .all(...roles) as CodeExampleRow[];
+
+    return rows.map(mapRowToPattern);
+  } else {
+    // Match patterns with ALL of the specified roles
+    const placeholders = roles.map(() => '?').join(', ');
+    const rows = db
+      .prepare(
+        `
+      SELECT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+      FROM code_examples ce
+      WHERE (
+        SELECT COUNT(DISTINCT pr.role)
+        FROM pattern_roles pr
+        WHERE pr.code_example_id = ce.id AND pr.role IN (${placeholders})
+      ) = ?
+      ORDER BY ce.title
+    `
+      )
+      .all(...roles, roles.length) as CodeExampleRow[];
+
+    return rows.map(mapRowToPattern);
+  }
+}
+
+/**
+ * Get patterns by role value (e.g., all patterns that target ".active").
+ */
+export async function getPatternsByRoleValue(
+  role: SemanticRole,
+  value: string,
+  options?: ConnectionOptions
+): Promise<Pattern[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  const rows = db
+    .prepare(
+      `
+    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+    FROM code_examples ce
+    INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
+    WHERE pr.role = ? AND pr.role_value LIKE ?
+    ORDER BY ce.title
+  `
+    )
+    .all(role, `%${value}%`) as CodeExampleRow[];
+
+  return rows.map(mapRowToPattern);
+}
+
+// =============================================================================
+// Role Statistics
+// =============================================================================
+
+/**
+ * Get statistics about role usage across all patterns.
+ */
+export async 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;
+}> {
+  const db = getDatabase({ ...options, readonly: true });
+
+  // Total roles
+  const totalRow = db.prepare('SELECT COUNT(*) as count FROM pattern_roles').get() as {
+    count: number;
+  };
+
+  // Count by role
+  const roleRows = db
+    .prepare(
+      `
+    SELECT role, COUNT(*) as count
+    FROM pattern_roles
+    GROUP BY role
+    ORDER BY count DESC
+  `
+    )
+    .all() as { role: string; count: number }[];
+
+  const byRole: Record<string, number> = {};
+  for (const row of roleRows) {
+    byRole[row.role] = row.count;
+  }
+
+  // Count by role type
+  const typeRows = db
+    .prepare(
+      `
+    SELECT role_type, COUNT(*) as count
+    FROM pattern_roles
+    WHERE role_type IS NOT NULL
+    GROUP BY role_type
+  `
+    )
+    .all() as { role_type: string; count: number }[];
+
+  const byRoleType: Record<string, number> = {};
+  for (const row of typeRows) {
+    byRoleType[row.role_type] = row.count;
+  }
+
+  // Top role values
+  const valueRows = db
+    .prepare(
+      `
+    SELECT role, role_value, COUNT(*) as count
+    FROM pattern_roles
+    WHERE role_value IS NOT NULL
+    GROUP BY role, role_value
+    ORDER BY count DESC
+    LIMIT 20
+  `
+    )
+    .all() as { role: string; role_value: string; count: number }[];
+
+  const topRoleValues = valueRows.map(row => ({
+    role: row.role as SemanticRole,
+    value: row.role_value,
+    count: row.count,
+  }));
+
+  // Patterns with/without roles
+  const withRolesRow = db
+    .prepare(
+      `
+    SELECT COUNT(DISTINCT code_example_id) as count
+    FROM pattern_roles
+  `
+    )
+    .get() as { count: number };
+
+  const totalPatternsRow = db.prepare('SELECT COUNT(*) as count FROM code_examples').get() as {
+    count: number;
+  };
+
+  return {
+    totalRoles: totalRow.count,
+    byRole: byRole as Record<SemanticRole, number>,
+    byRoleType: byRoleType as Record<RoleType, number>,
+    topRoleValues,
+    patternsWithRoles: withRolesRow.count,
+    patternsWithoutRoles: totalPatternsRow.count - withRolesRow.count,
+  };
+}
+
+/**
+ * Get role distribution for a specific command.
+ */
+export async function getRolesByCommand(
+  command: string,
+  options?: ConnectionOptions
+): Promise<Record<SemanticRole, number>> {
+  const db = getDatabase({ ...options, readonly: true });
+
+  const rows = db
+    .prepare(
+      `
+    SELECT pr.role, COUNT(*) as count
+    FROM pattern_roles pr
+    INNER JOIN code_examples ce ON pr.code_example_id = ce.id
+    WHERE ce.raw_code LIKE ?
+    GROUP BY pr.role
+  `
+    )
+    .all(`%${command}%`) as { role: string; count: number }[];
+
+  const result: Record<string, number> = {};
+  for (const row of rows) {
+    result[row.role] = row.count;
+  }
+  return result as Record<SemanticRole, number>;
+}
+
+// =============================================================================
+// Role Write Operations
+// =============================================================================
+
+/**
+ * Insert a pattern role into the database.
+ */
+export async function insertPatternRole(
+  role: Omit<PatternRole, 'id'>,
+  options?: ConnectionOptions
+): Promise<number> {
+  const db = getDatabase(options);
+  const result = db
+    .prepare(
+      `
+    INSERT INTO pattern_roles (code_example_id, command_index, role, role_value, role_type, required)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `
+    )
+    .run(
+      role.codeExampleId,
+      role.commandIndex,
+      role.role,
+      role.roleValue,
+      role.roleType,
+      role.required ? 1 : 0
+    );
+
+  return result.lastInsertRowid as number;
+}
+
+/**
+ * Delete all roles for a pattern.
+ */
+export async function deletePatternRoles(
+  patternId: string,
+  options?: ConnectionOptions
+): Promise<number> {
+  const db = getDatabase(options);
+  const result = db.prepare('DELETE FROM pattern_roles WHERE code_example_id = ?').run(patternId);
+  return result.changes;
+}
+
+/**
+ * Delete all roles from the database.
+ */
+export async function clearAllRoles(options?: ConnectionOptions): Promise<number> {
+  const db = getDatabase(options);
+  const result = db.prepare('DELETE FROM pattern_roles').run();
+  return result.changes;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Map database row to PatternRole type.
+ */
+function mapRowToPatternRole(row: PatternRoleRow): PatternRole {
+  return {
+    id: row.id,
+    codeExampleId: row.code_example_id,
+    commandIndex: row.command_index,
+    role: row.role as SemanticRole,
+    roleValue: row.role_value,
+    roleType: row.role_type as RoleType | null,
+    required: Boolean(row.required),
+  };
+}
+
+/**
+ * Map database row to Pattern type.
+ */
+function mapRowToPattern(row: CodeExampleRow): Pattern {
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description,
+    rawCode: row.raw_code,
+    category: row.feature,
+    primaryCommand: extractPrimaryCommand(row.raw_code),
+    tags: extractTags(row.raw_code),
+    difficulty: inferDifficulty(row.raw_code),
+    engine: (row.engine as EngineCompat) || null,
+    createdAt: new Date(row.created_at),
+  };
+}
+
+function extractPrimaryCommand(code: string): string | null {
+  const match = code.match(/^(on|toggle|put|set|add|remove|show|hide|wait|log|send|fetch|call)\b/i);
+  return match ? match[1].toLowerCase() : null;
+}
+
+function extractTags(code: string): string[] {
+  const tags: string[] = [];
+  if (code.includes('.')) tags.push('class');
+  if (code.includes('#')) tags.push('id');
+  if (code.includes('on ')) tags.push('event');
+  if (code.includes('fetch')) tags.push('async');
+  if (code.includes('wait')) tags.push('timing');
+  return tags;
+}
+
+function inferDifficulty(code: string): 'beginner' | 'intermediate' | 'advanced' {
+  const lines = code.split('\n').filter(l => l.trim()).length;
+  if (lines === 1 && !code.includes('then')) return 'beginner';
+  if (lines <= 3) return 'intermediate';
+  return 'advanced';
+}

package/src/api/translations.ts

@@ -0,0 +1,283 @@
+/**
+ * Translation Operations API
+ *
+ * Provides functions to query and manage translations.
+ */
+
+import { getDatabase } from '../database/connection';
+import type {
+  Translation,
+  VerificationResult,
+  WordOrder,
+  TranslationMethod,
+  ConnectionOptions,
+} from '../types';
+
+// =============================================================================
+// Database Row Types
+// =============================================================================
+
+interface PatternTranslationRow {
+  id: number;
+  code_example_id: string;
+  language: string;
+  hyperscript: string;
+  word_order: string;
+  translation_method: string;
+  confidence: number;
+  verified_parses: number;
+  verified_executes: number;
+  role_alignment_score: number | null;
+  created_at: string;
+  updated_at: string;
+}
+
+// =============================================================================
+// Query Functions
+// =============================================================================
+
+/**
+ * Get a translation for a pattern in a specific language.
+ */
+export async function getTranslation(
+  patternId: string,
+  language: string,
+  options?: ConnectionOptions
+): Promise<Translation | null> {
+  const db = getDatabase({ ...options, readonly: true });
+  const row = db
+    .prepare(
+      `
+    SELECT * FROM pattern_translations
+    WHERE code_example_id = ? AND language = ?
+  `
+    )
+    .get(patternId, language) as PatternTranslationRow | undefined;
+
+  return row ? mapRowToTranslation(row) : null;
+}
+
+/**
+ * Get all translations for a pattern.
+ */
+export async function getAllTranslations(
+  patternId: string,
+  options?: ConnectionOptions
+): Promise<Translation[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  const rows = db
+    .prepare(
+      `
+    SELECT * FROM pattern_translations
+    WHERE code_example_id = ?
+    ORDER BY language
+  `
+    )
+    .all(patternId) as PatternTranslationRow[];
+
+  return rows.map(mapRowToTranslation);
+}
+
+/**
+ * Get translations by language.
+ */
+export async function getTranslationsByLanguage(
+  language: string,
+  limit: number = 100,
+  options?: ConnectionOptions
+): Promise<Translation[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  const rows = db
+    .prepare(
+      `
+    SELECT * FROM pattern_translations
+    WHERE language = ?
+    ORDER BY confidence DESC
+    LIMIT ?
+  `
+    )
+    .all(language, limit) as PatternTranslationRow[];
+
+  return rows.map(mapRowToTranslation);
+}
+
+/**
+ * Get verified translations (successfully parsed).
+ */
+export async function getVerifiedTranslations(
+  language: string,
+  limit: number = 100,
+  options?: ConnectionOptions
+): Promise<Translation[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  const rows = db
+    .prepare(
+      `
+    SELECT * FROM pattern_translations
+    WHERE language = ? AND verified_parses = 1
+    ORDER BY confidence DESC
+    LIMIT ?
+  `
+    )
+    .all(language, limit) as PatternTranslationRow[];
+
+  return rows.map(mapRowToTranslation);
+}
+
+/**
+ * Get high-confidence translations.
+ */
+export async function getHighConfidenceTranslations(
+  minConfidence: number = 0.8,
+  limit: number = 100,
+  options?: ConnectionOptions
+): Promise<Translation[]> {
+  const db = getDatabase({ ...options, readonly: true });
+  const rows = db
+    .prepare(
+      `
+    SELECT * FROM pattern_translations
+    WHERE confidence >= ? AND verified_parses = 1
+    ORDER BY confidence DESC
+    LIMIT ?
+  `
+    )
+    .all(minConfidence, limit) as PatternTranslationRow[];
+
+  return rows.map(mapRowToTranslation);
+}
+
+/**
+ * Verify a translation parses correctly.
+ * Note: This requires @lokascript/semantic to be available.
+ */
+export async function verifyTranslation(
+  translation: Translation,
+  options?: ConnectionOptions
+): Promise<VerificationResult> {
+  let parseSuccess = false;
+  let errorMessage: string | null = null;
+  let confidence = translation.confidence;
+
+  try {
+    // Dynamic import to avoid bundling issues
+    const { canParse, parse } = await import('@lokascript/semantic');
+
+    if (canParse(translation.hyperscript, translation.language)) {
+      parse(translation.hyperscript, translation.language);
+      parseSuccess = true;
+    } else {
+      errorMessage = 'canParse returned false';
+    }
+  } catch (e) {
+    errorMessage = (e as Error).message;
+  }
+
+  // Update database
+  const db = getDatabase(options);
+  db.prepare(
+    `
+    UPDATE pattern_translations
+    SET verified_parses = ?, updated_at = datetime('now')
+    WHERE id = ?
+  `
+  ).run(parseSuccess ? 1 : 0, translation.id);
+
+  // Record test result
+  db.prepare(
+    `
+    INSERT INTO pattern_tests
+      (code_example_id, language, test_date, parse_success, error_message)
+    VALUES (?, ?, datetime('now'), ?, ?)
+  `
+  ).run(translation.codeExampleId, translation.language, parseSuccess ? 1 : 0, errorMessage);
+
+  return {
+    translation,
+    parseSuccess,
+    executeSuccess: false, // Not implemented yet
+    errorMessage,
+    confidence,
+    testedAt: new Date(),
+  };
+}
+
+/**
+ * Get translation statistics by language.
+ */
+export async function getTranslationStats(
+  options?: ConnectionOptions
+): Promise<Record<string, { total: number; verified: number; avgConfidence: number }>> {
+  const db = getDatabase({ ...options, readonly: true });
+
+  const rows = db
+    .prepare(
+      `
+    SELECT
+      language,
+      COUNT(*) as total,
+      SUM(verified_parses) as verified,
+      AVG(confidence) as avg_confidence
+    FROM pattern_translations
+    GROUP BY language
+  `
+    )
+    .all() as { language: string; total: number; verified: number; avg_confidence: number }[];
+
+  const stats: Record<string, { total: number; verified: number; avgConfidence: number }> = {};
+  for (const row of rows) {
+    stats[row.language] = {
+      total: row.total,
+      verified: row.verified,
+      avgConfidence: row.avg_confidence || 0,
+    };
+  }
+
+  return stats;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Map database row to Translation type.
+ */
+function mapRowToTranslation(row: PatternTranslationRow): Translation {
+  return {
+    id: row.id,
+    codeExampleId: row.code_example_id,
+    language: row.language,
+    hyperscript: row.hyperscript,
+    wordOrder: row.word_order as WordOrder,
+    translationMethod: row.translation_method as TranslationMethod,
+    confidence: row.confidence,
+    verifiedParses: row.verified_parses === 1,
+    verifiedExecutes: row.verified_executes === 1,
+    roleAlignmentScore: row.role_alignment_score ?? null,
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at),
+  };
+}
+
+/**
+ * Get word order for a language.
+ */
+export function getWordOrder(language: string): WordOrder {
+  const wordOrders: Record<string, WordOrder> = {
+    en: 'SVO',
+    es: 'SVO',
+    fr: 'SVO',
+    pt: 'SVO',
+    id: 'SVO',
+    sw: 'SVO',
+    zh: 'SVO',
+    ja: 'SOV',
+    ko: 'SOV',
+    tr: 'SOV',
+    qu: 'SOV',
+    ar: 'VSO',
+    de: 'V2',
+  };
+  return wordOrders[language] || 'SVO';
+}