@hyperfixi/patterns-reference 3.1.1 → 3.3.0

package/dist/{llm-B5nGz8V1.d.mts → llm-CCCSw-yp.d.ts}

@@ -1,4 +1,4 @@
-import { l as SearchOptions, C as ConnectionOptions, a as Pattern, k as PatternStats, o as Translation, W as WordOrder, r as VerificationResult, e as LLMExample } from './index-6GkHj5yJ.mjs';
+import { m as SearchOptions, C as ConnectionOptions, a as Pattern, l as PatternStats, p as Translation, W as WordOrder, s as VerificationResult, f as LLMExample, j as ExampleOptions } from './index-CoDUfq2P.js';
 
 /**
  * Pattern Queries API
@@ -19,7 +19,9 @@ declare function getPatternsByCategory(category: string, options?: ConnectionOpt
  */
 declare function getPatternsByCommand(command: string, options?: ConnectionOptions): Promise<Pattern[]>;
 /**
- * Search patterns by text query.
+ * Search patterns by text query: title, code or description — and, when a
+ * `language` is named, that language's translation, so a query in the language
+ * finds a pattern by its own code there.
  */
 declare function searchPatterns(query: string, searchOptions?: SearchOptions, connOptions?: ConnectionOptions): Promise<Pattern[]>;
 /**
@@ -67,8 +69,10 @@ declare function getVerifiedTranslations(language: string, limit?: number, optio
  */
 declare function getHighConfidenceTranslations(minConfidence?: number, limit?: number, options?: ConnectionOptions): Promise<Translation[]>;
 /**
- * Verify a translation parses correctly.
- * Note: This requires @lokascript/semantic to be available.
+ * Re-measure whether a translation parses, record the result, and return it.
+ * Uses the same definition sync-translations writes `verified_parses` with
+ * (src/sync/verify-parses.ts): every hyperscript body of the row parses in its
+ * language. Note: This requires @lokascript/semantic to be available.
  */
 declare function verifyTranslation(translation: Translation, options?: ConnectionOptions): Promise<VerificationResult>;
 /**
@@ -94,27 +98,33 @@ declare function getWordOrder(language: string): WordOrder;
  * Get LLM examples relevant to a prompt.
  * Uses text similarity to find relevant patterns.
  */
-declare function getLLMExamples(prompt: string, language?: string, limit?: number, options?: ConnectionOptions): Promise<LLMExample[]>;
+declare function getLLMExamples(prompt: string, language?: string, limit?: number, options?: ExampleOptions): Promise<LLMExample[]>;
 /**
  * Get examples by command type.
  */
-declare function getExamplesByCommand(command: string, language?: string, limit?: number, options?: ConnectionOptions): Promise<LLMExample[]>;
+declare function getExamplesByCommand(command: string, language?: string, limit?: number, options?: ExampleOptions): Promise<LLMExample[]>;
 /**
  * Get high-quality examples (for few-shot prompts).
  */
-declare function getHighQualityExamples(language?: string, minQuality?: number, limit?: number, options?: ConnectionOptions): Promise<LLMExample[]>;
+declare function getHighQualityExamples(language?: string, minQuality?: number, limit?: number, options?: ExampleOptions): Promise<LLMExample[]>;
 /**
  * Get most used examples (popular).
+ *
+ * @deprecated Only an explicit trackExampleUsage() call counts a use, and nothing
+ * makes one, so `usage_count` is 0 on every shipped example and this ranks by
+ * quality alone: getHighQualityExamples with no floor. Reads used to count
+ * themselves through the read-only handle they open; the write failed and the
+ * error was swallowed.
  */
-declare function getMostUsedExamples(language?: string, limit?: number, options?: ConnectionOptions): Promise<LLMExample[]>;
+declare function getMostUsedExamples(language?: string, limit?: number, options?: ExampleOptions): Promise<LLMExample[]>;
 /**
  * Build few-shot context for LLM prompting.
  */
-declare function buildFewShotContext(prompt: string, language?: string, numExamples?: number, options?: ConnectionOptions): Promise<string>;
+declare function buildFewShotContext(prompt: string, language?: string, numExamples?: number, options?: ExampleOptions): Promise<string>;
 /**
  * Add a new LLM example.
  */
-declare function addLLMExample(example: Omit<LLMExample, 'id' | 'usageCount' | 'createdAt'>, options?: ConnectionOptions): Promise<number>;
+declare function addLLMExample(example: Omit<LLMExample, 'id' | 'usageCount' | 'createdAt' | 'engine'>, options?: ConnectionOptions): Promise<number>;
 /**
  * Update example quality score.
  */
@@ -126,6 +136,7 @@ declare function getLLMStats(options?: ConnectionOptions): Promise<{
     total: number;
     byLanguage: Record<string, number>;
     avgQuality: number;
+    /** @deprecated 0 unless something calls trackExampleUsage() (see getMostUsedExamples). */
     totalUsage: number;
 }>;
 

package/dist/{llm-rEdJQScF.d.ts → llm-PxnriEZ_.d.mts}

@@ -1,4 +1,4 @@
-import { l as SearchOptions, C as ConnectionOptions, a as Pattern, k as PatternStats, o as Translation, W as WordOrder, r as VerificationResult, e as LLMExample } from './index-6GkHj5yJ.js';
+import { m as SearchOptions, C as ConnectionOptions, a as Pattern, l as PatternStats, p as Translation, W as WordOrder, s as VerificationResult, f as LLMExample, j as ExampleOptions } from './index-CoDUfq2P.mjs';
 
 /**
  * Pattern Queries API
@@ -19,7 +19,9 @@ declare function getPatternsByCategory(category: string, options?: ConnectionOpt
  */
 declare function getPatternsByCommand(command: string, options?: ConnectionOptions): Promise<Pattern[]>;
 /**
- * Search patterns by text query.
+ * Search patterns by text query: title, code or description — and, when a
+ * `language` is named, that language's translation, so a query in the language
+ * finds a pattern by its own code there.
  */
 declare function searchPatterns(query: string, searchOptions?: SearchOptions, connOptions?: ConnectionOptions): Promise<Pattern[]>;
 /**
@@ -67,8 +69,10 @@ declare function getVerifiedTranslations(language: string, limit?: number, optio
  */
 declare function getHighConfidenceTranslations(minConfidence?: number, limit?: number, options?: ConnectionOptions): Promise<Translation[]>;
 /**
- * Verify a translation parses correctly.
- * Note: This requires @lokascript/semantic to be available.
+ * Re-measure whether a translation parses, record the result, and return it.
+ * Uses the same definition sync-translations writes `verified_parses` with
+ * (src/sync/verify-parses.ts): every hyperscript body of the row parses in its
+ * language. Note: This requires @lokascript/semantic to be available.
  */
 declare function verifyTranslation(translation: Translation, options?: ConnectionOptions): Promise<VerificationResult>;
 /**
@@ -94,27 +98,33 @@ declare function getWordOrder(language: string): WordOrder;
  * Get LLM examples relevant to a prompt.
  * Uses text similarity to find relevant patterns.
  */
-declare function getLLMExamples(prompt: string, language?: string, limit?: number, options?: ConnectionOptions): Promise<LLMExample[]>;
+declare function getLLMExamples(prompt: string, language?: string, limit?: number, options?: ExampleOptions): Promise<LLMExample[]>;
 /**
  * Get examples by command type.
  */
-declare function getExamplesByCommand(command: string, language?: string, limit?: number, options?: ConnectionOptions): Promise<LLMExample[]>;
+declare function getExamplesByCommand(command: string, language?: string, limit?: number, options?: ExampleOptions): Promise<LLMExample[]>;
 /**
  * Get high-quality examples (for few-shot prompts).
  */
-declare function getHighQualityExamples(language?: string, minQuality?: number, limit?: number, options?: ConnectionOptions): Promise<LLMExample[]>;
+declare function getHighQualityExamples(language?: string, minQuality?: number, limit?: number, options?: ExampleOptions): Promise<LLMExample[]>;
 /**
  * Get most used examples (popular).
+ *
+ * @deprecated Only an explicit trackExampleUsage() call counts a use, and nothing
+ * makes one, so `usage_count` is 0 on every shipped example and this ranks by
+ * quality alone: getHighQualityExamples with no floor. Reads used to count
+ * themselves through the read-only handle they open; the write failed and the
+ * error was swallowed.
  */
-declare function getMostUsedExamples(language?: string, limit?: number, options?: ConnectionOptions): Promise<LLMExample[]>;
+declare function getMostUsedExamples(language?: string, limit?: number, options?: ExampleOptions): Promise<LLMExample[]>;
 /**
  * Build few-shot context for LLM prompting.
  */
-declare function buildFewShotContext(prompt: string, language?: string, numExamples?: number, options?: ConnectionOptions): Promise<string>;
+declare function buildFewShotContext(prompt: string, language?: string, numExamples?: number, options?: ExampleOptions): Promise<string>;
 /**
  * Add a new LLM example.
  */
-declare function addLLMExample(example: Omit<LLMExample, 'id' | 'usageCount' | 'createdAt'>, options?: ConnectionOptions): Promise<number>;
+declare function addLLMExample(example: Omit<LLMExample, 'id' | 'usageCount' | 'createdAt' | 'engine'>, options?: ConnectionOptions): Promise<number>;
 /**
  * Update example quality score.
  */
@@ -126,6 +136,7 @@ declare function getLLMStats(options?: ConnectionOptions): Promise<{
     total: number;
     byLanguage: Record<string, number>;
     avgQuality: number;
+    /** @deprecated 0 unless something calls trackExampleUsage() (see getMostUsedExamples). */
     totalUsage: number;
 }>;
 

package/dist/sync/index.d.mts

@@ -1,4 +1,4 @@
-import { D as DiscoveryResult, m as SyncOptions, n as SyncResult, V as ValidationOptions, q as ValidationResult } from '../index-6GkHj5yJ.mjs';
+import { D as DiscoveryResult, n as SyncOptions, o as SyncResult, V as ValidationOptions, r as ValidationResult } from '../index-CoDUfq2P.mjs';
 import '@lokascript/semantic';
 
 /**

package/dist/sync/index.d.ts

@@ -1,4 +1,4 @@
-import { D as DiscoveryResult, m as SyncOptions, n as SyncResult, V as ValidationOptions, q as ValidationResult } from '../index-6GkHj5yJ.js';
+import { D as DiscoveryResult, n as SyncOptions, o as SyncResult, V as ValidationOptions, r as ValidationResult } from '../index-CoDUfq2P.js';
 import '@lokascript/semantic';
 
 /**

package/dist/sync/index.js

@@ -30,7 +30,10 @@ function dbInputFiles(dbPath) {
   for (const f of [
     path.join(pr, "scripts", "init-db.ts"),
     path.join(pr, "scripts", "sync-translations.ts"),
-    path.join(pr, "src", "sync", "span-mask.ts"),
+    // Decides which markup `_` bodies are translated (and which stay English).
+    path.join(pr, "src", "sync", "markup-attributes.ts"),
+    // Writes every row's `verified_parses`.
+    path.join(pr, "src", "sync", "verify-parses.ts"),
     // Committed engine-verification results are seeded into the engine
     // column by init-db.ts, so they are DB input too.
     path.join(pr, "data", "engine-verification.json")

package/dist/sync/index.mjs

@@ -28,7 +28,10 @@ function dbInputFiles(dbPath) {
   for (const f of [
     join(pr, "scripts", "init-db.ts"),
     join(pr, "scripts", "sync-translations.ts"),
-    join(pr, "src", "sync", "span-mask.ts"),
+    // Decides which markup `_` bodies are translated (and which stay English).
+    join(pr, "src", "sync", "markup-attributes.ts"),
+    // Writes every row's `verified_parses`.
+    join(pr, "src", "sync", "verify-parses.ts"),
     // Committed engine-verification results are seeded into the engine
     // column by init-db.ts, so they are DB input too.
     join(pr, "data", "engine-verification.json")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/patterns-reference",
-  "version": "3.1.1",
+  "version": "3.3.0",
   "description": "Queryable patterns database for hyperscript with multilingual translations and LLM support",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,6 +25,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "pretest": "../../scripts/ensure-fresh.sh ../semantic",
     "test": "vitest",
     "test:run": "vitest run",
     "typecheck": "tsc --noEmit",
@@ -32,15 +33,13 @@
     "db:init:force": "tsx scripts/init-db.ts --force",
     "sync:translations": "tsx scripts/sync-translations.ts",
     "seed:llm": "tsx scripts/seed-llm-examples.ts",
-    "populate": "npm run db:init:force && npm run sync:translations && npm run seed:llm && npm run db:fix-translations",
-    "db:fix-translations": "tsx scripts/run-sql.ts scripts/fix-translations.sql",
+    "populate": "npm run db:init:force && npm run sync:translations && npm run seed:llm",
     "populate:dry-run": "npm run db:init:force && tsx scripts/sync-translations.ts --dry-run && tsx scripts/seed-llm-examples.ts --dry-run",
-    "validate": "tsx scripts/validate-all.ts",
-    "validate:fix": "tsx scripts/validate-all.ts --fix",
     "verify": "tsx scripts/verify-translations.ts",
     "verify:verbose": "tsx scripts/verify-translations.ts --verbose",
     "test:check": "VITEST_QUIET=1 bash ../../scripts/vitest-run.sh --reporter=dot",
-    "verify:engines": "tsx scripts/verify-engines.ts --update-db"
+    "verify:engines": "tsx scripts/verify-engines.ts --update-db",
+    "verify:engines:check": "tsx scripts/verify-engines.ts --check"
   },
   "keywords": [
     "hyperscript",
@@ -66,21 +65,22 @@
   },
   "homepage": "https://github.com/codetalcott/hyperfixi/tree/main/packages/patterns-reference#readme",
   "dependencies": {
-    "@lokascript/semantic": "^3.1.1",
-    "better-sqlite3": "^13.0.1"
+    "@lokascript/semantic": "^3.3.0",
+    "better-sqlite3": "^13.0.3"
   },
   "devDependencies": {
-    "@hyperfixi/core": "^3.1.1",
-    "@hyperfixi/reactivity": "^3.1.1",
-    "@hyperfixi/realtime": "^3.1.1",
-    "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^26.1.2",
+    "@hyperfixi/components": "^3.3.0",
+    "@hyperfixi/core": "^3.3.0",
+    "@hyperfixi/reactivity": "^3.3.0",
+    "@hyperfixi/realtime": "^3.3.0",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.6.3",
     "hyperscript.org": "0.9.93",
-    "jsdom": "^30.0.0",
+    "jsdom": "^30.1.1",
     "tsup": "^8.0.0",
-    "tsx": "^4.23.1",
+    "tsx": "^4.23.15",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.5"
+    "vitest": "^5.0.2"
   },
   "files": [
     "dist",

package/src/adapters/llm-adapter.ts

@@ -9,7 +9,8 @@
  */
 
 import { getDatabase, closeDatabase } from '../database/connection';
-import type { LLMExample, ConnectionOptions } from '../types';
+import type { LLMExample, ConnectionOptions, EngineCompat } from '../types';
+import { exampleCondition } from '../api/engine-filter';
 import {
   getLLMExamples,
   getExamplesByCommand,
@@ -32,8 +33,17 @@ export interface LLMExampleRecord {
   completion: string;
   language: string;
   qualityScore: number;
+  /** The engine(s) verified to run the example's pattern (never null here). */
+  engine: EngineCompat | null;
 }
 
+/** Every sync example query reads through this join; see api/engine-filter.ts. */
+const RECORDS_FROM = `
+  SELECT le.id, le.prompt, le.completion, le.language, le.quality_score as qualityScore,
+         ce.engine AS engine
+  FROM llm_examples le
+  JOIN code_examples ce ON ce.id = le.code_example_id`;
+
 /**
  * Database row type for internal use
  */
@@ -73,16 +83,20 @@ export function isDatabaseAvailable(): boolean {
  * @param prompt - The user's request/prompt
  * @param language - Target language code (default: 'en')
  * @param limit - Maximum number of examples to return (default: 5)
+ * @param engine - Only examples whose pattern runs on this engine. Examples no
+ *   engine runs are never returned, with or without it.
  */
 export function findRelevantExamples(
   prompt: string,
   language: string = 'en',
-  limit: number = 5
+  limit: number = 5,
+  engine?: EngineCompat
 ): LLMExampleRecord[] {
   if (!syncDatabaseAvailable) return [];
 
   try {
     const db = getDatabase({ readonly: true });
+    const runs = exampleCondition('ce.engine', engine);
 
     // Extract keywords from prompt
     const keywords = extractKeywords(prompt);
@@ -91,43 +105,33 @@ export function findRelevantExamples(
       // Return top-quality examples as fallback
       const rows = db
         .prepare(
-          `
-        SELECT id, prompt, completion, language, quality_score as qualityScore
-        FROM llm_examples
-        WHERE language = ?
-        ORDER BY quality_score DESC, usage_count DESC
+          `${RECORDS_FROM}
+        WHERE le.language = ? AND ${runs.sql}
+        ORDER BY le.quality_score DESC, le.usage_count DESC
         LIMIT ?
       `
         )
-        .all(language, limit) as LLMExampleRecord[];
+        .all(language, ...runs.params, limit) as LLMExampleRecord[];
 
-      trackUsageSync(
-        db,
-        rows.map(r => r.id)
-      );
       return rows;
     }
 
     // Build LIKE clauses for keyword matching
-    const likeClauses = keywords.map(() => '(prompt LIKE ? OR completion LIKE ?)').join(' OR ');
+    const likeClauses = keywords
+      .map(() => '(le.prompt LIKE ? OR le.completion LIKE ?)')
+      .join(' OR ');
     const params = keywords.flatMap(k => [`%${k}%`, `%${k}%`]);
 
     const rows = db
       .prepare(
-        `
-      SELECT id, prompt, completion, language, quality_score as qualityScore
-      FROM llm_examples
-      WHERE language = ? AND (${likeClauses})
-      ORDER BY quality_score DESC
+        `${RECORDS_FROM}
+      WHERE le.language = ? AND ${runs.sql} AND (${likeClauses})
+      ORDER BY le.quality_score DESC
       LIMIT ?
     `
       )
-      .all(language, ...params, limit) as LLMExampleRecord[];
+      .all(language, ...runs.params, ...params, limit) as LLMExampleRecord[];
 
-    trackUsageSync(
-      db,
-      rows.map(r => r.id)
-    );
     return rows;
   } catch (error) {
     console.warn(
@@ -145,24 +149,24 @@ export function findRelevantExamples(
 export function findExamplesByCommand(
   command: string,
   language: string = 'en',
-  limit: number = 5
+  limit: number = 5,
+  engine?: EngineCompat
 ): LLMExampleRecord[] {
   if (!syncDatabaseAvailable) return [];
 
   try {
     const db = getDatabase({ readonly: true });
+    const runs = exampleCondition('ce.engine', engine);
 
     const rows = db
       .prepare(
-        `
-      SELECT id, prompt, completion, language, quality_score as qualityScore
-      FROM llm_examples
-      WHERE language = ? AND completion LIKE ?
-      ORDER BY quality_score DESC
+        `${RECORDS_FROM}
+      WHERE le.language = ? AND ${runs.sql} AND le.completion LIKE ?
+      ORDER BY le.quality_score DESC
       LIMIT ?
     `
       )
-      .all(language, `%${command}%`, limit) as LLMExampleRecord[];
+      .all(language, ...runs.params, `%${command}%`, limit) as LLMExampleRecord[];
 
     return rows;
   } catch (error) {
@@ -180,9 +184,10 @@ export function findExamplesByCommand(
 export function buildFewShotContextSync(
   prompt: string,
   language: string = 'en',
-  numExamples: number = 3
+  numExamples: number = 3,
+  engine?: EngineCompat
 ): string {
-  const examples = findRelevantExamples(prompt, language, numExamples);
+  const examples = findRelevantExamples(prompt, language, numExamples, engine);
 
   if (examples.length === 0) {
     return '';
@@ -202,6 +207,10 @@ export function buildFewShotContextSync(
 
 /**
  * Track example usage (sync interface).
+ *
+ * @deprecated The counts go into the installed package's own database file,
+ * which every install and every `populate` replaces, and only
+ * getMostUsedExamples (deprecated with it) reads them. Nothing calls this.
  */
 export function trackExampleUsage(ids: number[]): void {
   if (!syncDatabaseAvailable || ids.length === 0) return;
@@ -376,16 +385,29 @@ export function createLLMAdapter(options?: ConnectionOptions) {
     isDatabaseAvailable,
 
     // Async methods (preferred for new code)
-    getLLMExamples: (prompt: string, language?: string, limit?: number) =>
-      getLLMExamples(prompt, language, limit, options),
-    getExamplesByCommand: (command: string, language?: string, limit?: number) =>
-      getExamplesByCommand(command, language, limit, options),
-    getHighQualityExamples: (language?: string, minQuality?: number, limit?: number) =>
-      getHighQualityExamples(language, minQuality, limit, options),
-    getMostUsedExamples: (language?: string, limit?: number) =>
-      getMostUsedExamples(language, limit, options),
-    buildFewShotContext: (prompt: string, language?: string, numExamples?: number) =>
-      buildFewShotContext(prompt, language, numExamples, options),
+    getLLMExamples: (prompt: string, language?: string, limit?: number, engine?: EngineCompat) =>
+      getLLMExamples(prompt, language, limit, { ...options, engine }),
+    getExamplesByCommand: (
+      command: string,
+      language?: string,
+      limit?: number,
+      engine?: EngineCompat
+    ) => getExamplesByCommand(command, language, limit, { ...options, engine }),
+    getHighQualityExamples: (
+      language?: string,
+      minQuality?: number,
+      limit?: number,
+      engine?: EngineCompat
+    ) => getHighQualityExamples(language, minQuality, limit, { ...options, engine }),
+    /** @deprecated See getMostUsedExamples. */
+    getMostUsedExamples: (language?: string, limit?: number, engine?: EngineCompat) =>
+      getMostUsedExamples(language, limit, { ...options, engine }),
+    buildFewShotContext: (
+      prompt: string,
+      language?: string,
+      numExamples?: number,
+      engine?: EngineCompat
+    ) => buildFewShotContext(prompt, language, numExamples, { ...options, engine }),
     getLLMStats: () => getLLMStats(options),
 
     // Cleanup

package/src/api/engine-filter.ts

@@ -0,0 +1,37 @@
+/**
+ * Selecting patterns by the engine that runs them.
+ *
+ * `code_examples.engine` is mechanically verified (scripts/verify-engines.ts;
+ * CI's `verify:engines:check`): 'both', 'lokascript' (hyperfixi only),
+ * 'hyperscript' (upstream _hyperscript only) or NULL (verified on neither).
+ */
+
+import type { EngineCompat } from '../types';
+
+/**
+ * SQL for "the pattern runs on `engine`" over an engine column. A pattern
+ * verified on both engines runs on either, so 'hyperscript' and 'lokascript'
+ * include 'both'. `null` selects the patterns no engine runs.
+ */
+export function runsOn(
+  column: string,
+  engine: EngineCompat | null
+): { sql: string; params: string[] } {
+  if (engine === null) return { sql: `${column} IS NULL`, params: [] };
+  if (engine === 'both') return { sql: `${column} = 'both'`, params: [] };
+  return { sql: `${column} IN ('both', ?)`, params: [engine] };
+}
+
+/**
+ * The condition for serving LLM examples. An example is code handed to a
+ * generator as correct, so one whose pattern NO engine runs is never served;
+ * `engine` narrows further to what a particular runtime accepts.
+ */
+export function exampleCondition(
+  column: string,
+  engine: EngineCompat | undefined
+): { sql: string; params: string[] } {
+  return engine === undefined
+    ? { sql: `${column} IS NOT NULL`, params: [] }
+    : runsOn(column, engine);
+}