@hyperfixi/patterns-reference 2.5.1 → 2.7.0

package/dist/sync/index.mjs

@@ -1,3 +1,70 @@
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { relative, sep, resolve, dirname, join } from 'path';
+
+// src/sync/db-stamp.ts
+function repoRootFromDbPath(dbPath) {
+  return resolve(dirname(dbPath), "..", "..", "..");
+}
+function walkTsFiles(dir, acc) {
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir).sort()) {
+    if (name === "node_modules" || name === "dist" || name === "__tests__") continue;
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walkTsFiles(full, acc);
+    } else if (name.endsWith(".ts") && !name.endsWith(".test.ts") && !name.endsWith(".d.ts")) {
+      acc.push(full);
+    }
+  }
+}
+function dbInputFiles(dbPath) {
+  const root = repoRootFromDbPath(dbPath);
+  const files = [];
+  walkTsFiles(join(root, "packages", "i18n", "src"), files);
+  walkTsFiles(join(root, "packages", "semantic", "src"), files);
+  const pr = join(root, "packages", "patterns-reference");
+  for (const f of [
+    join(pr, "scripts", "init-db.ts"),
+    join(pr, "scripts", "sync-translations.ts"),
+    join(pr, "src", "sync", "span-mask.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")
+  ]) {
+    if (existsSync(f)) files.push(f);
+  }
+  return files.sort();
+}
+function computeDbInputHash(dbPath) {
+  const root = repoRootFromDbPath(dbPath);
+  const files = dbInputFiles(dbPath);
+  const h = createHash("sha256");
+  h.update(`files:${files.length}\0`);
+  for (const f of files) {
+    h.update(relative(root, f).split(sep).join("/"));
+    h.update("\0");
+    h.update(readFileSync(f));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+function dbStampPath(dbPath) {
+  return `${dbPath}.stamp`;
+}
+function writeDbStamp(dbPath) {
+  writeFileSync(dbStampPath(dbPath), `${computeDbInputHash(dbPath)}
+`, "utf8");
+}
+function checkDbStamp(dbPath) {
+  const sp = dbStampPath(dbPath);
+  if (!existsSync(sp)) return { status: "unstamped" };
+  const expected = readFileSync(sp, "utf8").trim();
+  const actual = computeDbInputHash(dbPath);
+  return actual === expected ? { status: "ok" } : { status: "stale", expected, actual };
+}
+
 // src/sync/index.ts
 async function syncTranslations(_options = {}) {
   throw new Error(
@@ -20,4 +87,4 @@ async function seedLLMExamples(_dryRun = false) {
   );
 }
 
-export { discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations };
+export { checkDbStamp, computeDbInputHash, dbStampPath, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations, writeDbStamp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/patterns-reference",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "Queryable patterns database for hyperscript with multilingual translations and LLM support",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -39,10 +39,8 @@
     "validate:fix": "tsx scripts/validate-all.ts --fix",
     "verify": "tsx scripts/verify-translations.ts",
     "verify:verbose": "tsx scripts/verify-translations.ts --verbose",
-    "verify:engine": "tsx scripts/verify-engine-compat.ts",
-    "verify:engine:verbose": "tsx scripts/verify-engine-compat.ts --verbose",
-    "verify:engine:dry-run": "tsx scripts/verify-engine-compat.ts --dry-run --verbose",
-    "test:check": "vitest run --reporter=dot 2>&1 | tail -5"
+    "test:check": "VITEST_QUIET=1 bash ../../scripts/vitest-run.sh --reporter=dot",
+    "verify:engines": "tsx scripts/verify-engines.ts --update-db"
   },
   "keywords": [
     "hyperscript",
@@ -56,7 +54,7 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24"
   },
   "repository": {
     "type": "git",
@@ -68,12 +66,17 @@
   },
   "homepage": "https://github.com/codetalcott/hyperfixi/tree/main/packages/patterns-reference#readme",
   "dependencies": {
-    "@lokascript/semantic": "^2.5.1",
+    "@lokascript/semantic": "^2.7.0",
     "better-sqlite3": "^12.6.2"
   },
   "devDependencies": {
+    "@hyperfixi/core": "^2.7.0",
+    "@hyperfixi/reactivity": "^2.7.0",
+    "@hyperfixi/realtime": "^2.7.0",
     "@types/better-sqlite3": "^7.6.0",
     "@types/node": "^20.0.0",
+    "hyperscript.org": "0.9.93",
+    "jsdom": "^26.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0",

package/src/api/patterns.ts

@@ -225,12 +225,14 @@ export async function getPatternStats(connOptions?: ConnectionOptions): Promise<
 /**
  * Get behavior definition patterns.
  *
- * Returns patterns with feature='behavior' — these are installable
- * behavior definitions (behavior Name(params) ... end) that can be
- * compiled and registered with a LokaScript runtime.
+ * Returns installable behavior definitions (behavior Name(params) ... end)
+ * that can be compiled and registered with a LokaScript runtime. The
+ * 'behavior' category also holds usage examples (`install Draggable`,
+ * `tell #modal …`), so filter to actual definitions by source shape.
  */
 export async function getBehaviorPatterns(options?: ConnectionOptions): Promise<Pattern[]> {
-  return getPatternsByCategory('behavior', options);
+  const patterns = await getPatternsByCategory('behavior', options);
+  return patterns.filter(p => /^\s*behavior\s/.test(p.rawCode));
 }
 
 // =============================================================================

package/src/database/connection.ts

@@ -24,6 +24,15 @@ const DEFAULT_DB_PATH =
 let dbInstance: InstanceType<typeof Database> | null = null;
 let currentDbPath: string | null = null;
 
+/**
+ * The resolved default DB path (honouring `LSP_DB_PATH` / `HYPERSCRIPT_LSP_DB`).
+ * Exposed so callers (e.g. the multilingual gate's freshness check) can target the
+ * exact DB that `getDatabase()` opens.
+ */
+export function getDefaultDbPath(): string {
+  return DEFAULT_DB_PATH;
+}
+
 /**
  * Get database connection (lazy singleton).
  */

package/src/index.ts

@@ -83,6 +83,7 @@ export {
   resetConnection,
   isConnected,
   getCurrentDbPath,
+  getDefaultDbPath,
 } from './database/connection';
 
 // =============================================================================
@@ -166,6 +167,11 @@ export {
   validateAllTranslations,
   discoverPatterns,
   seedLLMExamples,
+  computeDbInputHash,
+  dbStampPath,
+  writeDbStamp,
+  checkDbStamp,
+  type DbStampStatus,
 } from './sync';
 
 // =============================================================================

package/src/sync/db-stamp.ts

@@ -0,0 +1,111 @@
+/**
+ * DB provenance stamp — guards against running the multilingual gate against a
+ * `patterns.db` that was generated from *different* source than is currently checked
+ * out (the cross-branch "phantom regression" footgun).
+ *
+ * The DB's content (transformer translation text + stored parser confidence /
+ * verified_parses) is determined by the i18n + semantic **source**, plus the seed and
+ * sync scripts. We hash that source (not the gitignored, build-non-deterministic
+ * `dist/`) so the stamp catches a branch / source change regardless of whether `dist`
+ * happened to be rebuilt. `sync-translations` writes the stamp next to the DB; the
+ * gate verifies it before trusting a comparison against the committed baseline.
+ *
+ * The stamp file (`patterns.db.stamp`) is a **local** artifact (gitignored) — it
+ * records "what source produced *my* local DB", which is exactly what the gate needs
+ * to confirm the DB is fresh for the current working tree.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Resolve the monorepo root from a `patterns.db` path. Standard layout:
+ * `<root>/packages/patterns-reference/data/patterns.db` → up 3 from `data/`.
+ */
+function repoRootFromDbPath(dbPath: string): string {
+  return resolve(dirname(dbPath), '..', '..', '..');
+}
+
+/** Recursively collect non-test `.ts` source files under `dir`. */
+function walkTsFiles(dir: string, acc: string[]): void {
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir).sort()) {
+    if (name === 'node_modules' || name === 'dist' || name === '__tests__') continue;
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walkTsFiles(full, acc);
+    } else if (name.endsWith('.ts') && !name.endsWith('.test.ts') && !name.endsWith('.d.ts')) {
+      acc.push(full);
+    }
+  }
+}
+
+/**
+ * The source files whose content determines `patterns.db`: the i18n transformer +
+ * dictionaries + grammar profiles (translation text), the semantic parser + profiles
+ * (stored confidence + the language set), and the seed / sync scripts.
+ */
+function dbInputFiles(dbPath: string): string[] {
+  const root = repoRootFromDbPath(dbPath);
+  const files: string[] = [];
+  walkTsFiles(join(root, 'packages', 'i18n', 'src'), files);
+  walkTsFiles(join(root, 'packages', 'semantic', 'src'), files);
+  const pr = join(root, 'packages', 'patterns-reference');
+  for (const f of [
+    join(pr, 'scripts', 'init-db.ts'),
+    join(pr, 'scripts', 'sync-translations.ts'),
+    join(pr, 'src', 'sync', 'span-mask.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'),
+  ]) {
+    if (existsSync(f)) files.push(f);
+  }
+  return files.sort();
+}
+
+/**
+ * Compute the provenance hash of the DB's source inputs. Stable across machines (it
+ * hashes committed source, keyed by repo-relative path).
+ */
+export function computeDbInputHash(dbPath: string): string {
+  const root = repoRootFromDbPath(dbPath);
+  const files = dbInputFiles(dbPath);
+  const h = createHash('sha256');
+  h.update(`files:${files.length}\0`);
+  for (const f of files) {
+    h.update(relative(root, f).split(sep).join('/'));
+    h.update('\0');
+    h.update(readFileSync(f));
+    h.update('\0');
+  }
+  return h.digest('hex');
+}
+
+export function dbStampPath(dbPath: string): string {
+  return `${dbPath}.stamp`;
+}
+
+/** Write the provenance stamp next to the DB (called at the end of sync). */
+export function writeDbStamp(dbPath: string): void {
+  writeFileSync(dbStampPath(dbPath), `${computeDbInputHash(dbPath)}\n`, 'utf8');
+}
+
+export type DbStampStatus =
+  | { status: 'ok' }
+  | { status: 'unstamped' }
+  | { status: 'stale'; expected: string; actual: string };
+
+/**
+ * Verify the DB's stamp against the current source. `unstamped` (no sidecar) is
+ * returned when the DB predates this guard — callers should warn, not hard-fail.
+ */
+export function checkDbStamp(dbPath: string): DbStampStatus {
+  const sp = dbStampPath(dbPath);
+  if (!existsSync(sp)) return { status: 'unstamped' };
+  const expected = readFileSync(sp, 'utf8').trim();
+  const actual = computeDbInputHash(dbPath);
+  return actual === expected ? { status: 'ok' } : { status: 'stale', expected, actual };
+}

package/src/sync/index.ts

@@ -68,3 +68,12 @@ export async function seedLLMExamples(_dryRun: boolean = false): Promise<{ count
     'seedLLMExamples should be run via: bun run packages/semantic/scripts/seed-llm-examples.ts'
   );
 }
+
+// DB provenance stamp — freshness guard for the multilingual gate.
+export {
+  computeDbInputHash,
+  dbStampPath,
+  writeDbStamp,
+  checkDbStamp,
+  type DbStampStatus,
+} from './db-stamp';

package/src/sync/span-mask.ts

@@ -0,0 +1,166 @@
+/**
+ * Span-aware masking for hyperscript code prior to translation.
+ *
+ * The grammar transformer and keyword-substitute fallback both treat hyperscript
+ * source as a flat token stream. They will happily reorder text inside HTML
+ * elements, translate words inside string literals, and shred bracket
+ * expressions like `[key is 'Escape']`. To avoid that, we replace
+ * non-translatable spans with opaque placeholder tokens before translation,
+ * then restore them after.
+ *
+ * Placeholders use the form `__HFXMSK_<idx>_<KIND>__`. Underscores on both
+ * sides make the placeholder a single "word" to JS regex `\b` boundaries —
+ * keyword substitution `\bword\b` cannot match a substring inside the
+ * placeholder, regardless of case-insensitivity flags.
+ */
+
+export type SpanKind =
+  | 'string-single'
+  | 'string-double'
+  | 'string-template'
+  | 'url'
+  | 'html-text'
+  | 'directive'
+  | 'bracket-expr'
+  | 'js-block';
+
+export interface MaskedSpan {
+  kind: SpanKind;
+  original: string;
+  placeholder: string;
+}
+
+export interface MaskResult {
+  masked: string;
+  spans: MaskedSpan[];
+}
+
+const KIND_TAG: Record<SpanKind, string> = {
+  'string-single': 'STR1',
+  'string-double': 'STR2',
+  'string-template': 'STRT',
+  url: 'URL',
+  'html-text': 'TEXT',
+  directive: 'DIR',
+  'bracket-expr': 'BRK',
+  'js-block': 'JS',
+};
+
+function makePlaceholder(kind: SpanKind, idx: number): string {
+  return `__HFXMSK_${idx}_${KIND_TAG[kind]}__`;
+}
+
+const PLACEHOLDER_RE = /__HFXMSK_(\d+)_(?:STR1|STR2|STRT|URL|TEXT|DIR|BRK|JS)__/g;
+
+/**
+ * Detect non-translatable spans in hyperscript code and replace them with
+ * opaque placeholders. The detection order is significant: earlier rules
+ * consume characters that later rules would otherwise misinterpret.
+ *
+ *   1. Template literals  (consume `${...}` interpolation contents)
+ *   2. Double-quoted strings (consume HTML attribute values)
+ *   3. Single-quoted strings (escaping possessive `'s`)
+ *   4. HTML inner text  (between `>` and `<` with non-whitespace)
+ *   5. Bracket expressions  (event filters like `[key is 'Escape']`)
+ *   6. URL-like tokens  (paths and protocol://host)
+ *   7. Component template directives  (`#if`, `#end`, `#for`, ...)
+ */
+export function maskSpans(input: string): MaskResult {
+  let working = input;
+  const spans: MaskedSpan[] = [];
+
+  const record = (kind: SpanKind, original: string): string => {
+    const placeholder = makePlaceholder(kind, spans.length);
+    spans.push({ kind, original, placeholder });
+    return placeholder;
+  };
+
+  // 0. Embedded JS blocks: `js(args) ... end` opens a raw-JavaScript escape
+  //    hatch inside hyperscript. Its body must be passed through verbatim;
+  //    the grammar transformer would otherwise tokenize JavaScript as if
+  //    it were hyperscript and silently drop unrecognized tokens. Mask this
+  //    first because the body can contain any other span kind.
+  working = working.replace(/\bjs\([^)]*\)[\s\S]*?\bend\b/g, m => record('js-block', m));
+
+  // 1. Template literals — match outermost backtick body with escape support.
+  //    The body may contain `${...}` interpolations; treat the whole literal
+  //    as one opaque span. Inner code stays English but is structurally safe.
+  working = working.replace(/`(?:\\.|[^`\\])*`/g, m => record('string-template', m));
+
+  // 2. Double-quoted strings. This also captures HTML attribute values so
+  //    `component="my-layout"` cannot have `my` translated.
+  working = working.replace(/"(?:\\.|[^"\\])*"/g, m => record('string-double', m));
+
+  // 3. Single-quoted strings, but NOT possessive `'s` (preceded by a word char).
+  //    The lookbehind ensures `me's value 'foo'` matches only `'foo'`.
+  working = working.replace(/(?<!\w)'(?:\\.|[^'\\])*'/g, m => record('string-single', m));
+
+  // 4. HTML inner text content. Match a non-whitespace text run between
+  //    a `>` and the next `<`, on the SAME line. Newline confinement is
+  //    critical: without it the regex would span multiple element boundaries
+  //    and consume nested tags as if they were text. The middle character
+  //    class `[^<\n\s]` ensures at least one printable non-`<` char exists
+  //    so pure indentation between elements is not masked.
+  //    The `(?<!\/)` lookbehind excludes a `>` that closes a SELF-CLOSING
+  //    selector literal (`<button/>`): hyperscript between two selector
+  //    literals (`… last <button/> in .modal focus first <button/> …`) is
+  //    real code, not element inner text — masking it hid the whole segment
+  //    from the transformer, which then emitted it untranslated (the
+  //    focus-trap `focus first` leak).
+  working = working.replace(
+    /(?<!\/)>([^<\n]*[^<\n\s][^<\n]*)</g,
+    (_m, text) => `>${record('html-text', text)}<`
+  );
+
+  // 5. Bracket expressions. Mask the entire `[...]` payload as one unit so
+  //    SOV/VSO reordering cannot move tokens out of the brackets. Non-nested
+  //    is fine for the current corpus; bracket-inside-bracket isn't used.
+  working = working.replace(/\[[^\]]*\]/g, m => record('bracket-expr', m));
+
+  // 6. URL-like tokens. Two forms:
+  //      - protocol://host  (http, https, ws, wss, file)
+  //      - /path  (whitespace-bounded, not preceded by a word char to avoid
+  //                matching arithmetic like `1/2`)
+  //    The path form matches a bare `/` too (precache root) when followed
+  //    by non-word boundary. Path chars: word, dash, dot, slash, glob, query.
+  working = working.replace(/(?:https?|wss?|file):\/\/[^\s,)]+|(?<![\w<])\/[\w\-./*?=&]*/g, m =>
+    record('url', m)
+  );
+
+  // 7. Component template directives. Mask the `#keyword` token only — the
+  //    expression after it (e.g. `^user.admin`) is left translatable, since
+  //    those are typically variable references that pass through unchanged.
+  working = working.replace(/#(?:if|else|elif|end|for|each)\b/g, m => record('directive', m));
+
+  return { masked: working, spans };
+}
+
+/**
+ * Restore placeholders to their original spans. Iterates to a fixed point so
+ * that an `original` field containing another placeholder (which shouldn't
+ * happen with the current detection rules, but is cheap insurance) is fully
+ * resolved.
+ */
+export function unmaskSpans(translated: string, spans: MaskedSpan[]): string {
+  let result = translated;
+  let prev: string;
+  do {
+    prev = result;
+    result = result.replace(PLACEHOLDER_RE, (m, idx) => {
+      const span = spans[Number(idx)];
+      return span ? span.original : m;
+    });
+  } while (result !== prev);
+  return result;
+}
+
+/**
+ * Convenience wrapper: mask, run a transform on the masked surface, then
+ * unmask. The transform receives only the masked string and must preserve
+ * placeholders (which it will, since they look like ordinary identifiers).
+ */
+export function withMaskedSpans(input: string, transform: (masked: string) => string): string {
+  const { masked, spans } = maskSpans(input);
+  const transformed = transform(masked);
+  return unmaskSpans(transformed, spans);
+}