@techninja/clearstack 0.4.3 → 0.4.4

package/lib/spec-i18n-locales.js

@@ -0,0 +1,84 @@
+/**
+ * Locale file parsing helpers for i18n spec check.
+ * @module lib/spec-i18n-locales
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+/**
+ * Try to run `npx hybrids extract ./src` and parse the JSON output.
+ * @param {string} root
+ * @returns {Record<string, object>|null}
+ */
+export function tryHybridsExtract(root) {
+  const srcDir = resolve(root, 'src');
+  if (!existsSync(srcDir)) return null;
+  try {
+    const out = execSync('npx hybrids extract ./src', {
+      cwd: root,
+      encoding: 'utf-8',
+      timeout: 30000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse locale keys from a .js file that calls localize(lang, {...}).
+ * Extracts top-level string keys from the object literal.
+ * @param {string} filePath
+ * @returns {Set<string>}
+ */
+export function parseLocaleJs(filePath) {
+  const src = readFileSync(filePath, 'utf-8');
+  const keys = new Set();
+  const re = /^\s*(['"])(.*?)\1\s*:/gm;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    const key = m[2].replace(/\\'/g, "'").replace(/\\"/g, '"');
+    keys.add(key);
+  }
+  return keys;
+}
+
+/**
+ * Parse locale keys from a .json file.
+ * @param {string} filePath
+ * @returns {Set<string>}
+ */
+export function parseLocaleJson(filePath) {
+  try {
+    const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+    return new Set(Object.keys(data));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Find locale files and return { lang, keys } for each.
+ * @param {string} localesDir
+ * @returns {Array<{lang: string, keys: Set<string>, file: string}>}
+ */
+export function loadLocales(localesDir) {
+  if (!localesDir) return [];
+  const files = readdirSync(localesDir);
+  const locales = [];
+  for (const f of files) {
+    if (f === 'overrides.json' || f === 'en.json') continue;
+    const full = resolve(localesDir, f);
+    if (f.endsWith('.json')) {
+      const lang = f.replace(/\.json$/, '');
+      locales.push({ lang, keys: parseLocaleJson(full), file: f });
+    } else if (f.endsWith('.js') && !f.includes('init')) {
+      const lang = f.replace(/\.js$/, '');
+      locales.push({ lang, keys: parseLocaleJs(full), file: f });
+    }
+  }
+  return locales;
+}

package/lib/spec-i18n.js

@@ -1,12 +1,13 @@
 /**
- * i18n readiness check — detects patterns, locale files, hardcoded prose density.
+ * i18n readiness check — uses Hybrids extract when available, falls back to regex.
  * Always passes (informational). Surfaces coverage gaps without blocking the build.
  * @module lib/spec-i18n
  */
 
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { findFiles, elapsed } from './spec-utils.js';
+import { tryHybridsExtract, loadLocales } from './spec-i18n-locales.js';
 
 /** @typedef {import('./spec-utils.js').CheckResult} CheckResult */
 
@@ -17,9 +18,6 @@ const LOC_RE = /\blocalize\s*\(/;
 const INIT_RE = /loadLocale|localize\s*\(/;
 const TPL_RE = /html`[\s\S]*?`/g;
 
-/** Strip leading > and trailing <$ from a prose match, trim. */
-const cleanHit = (h) => h.replace(/^>\s*/, '').replace(/\s*[<$]$/, '').trim();
-
 /**
  * Check i18n readiness — informational, always passes.
  * @param {string} root
@@ -30,6 +28,7 @@ const cleanHit = (h) => h.replace(/^>\s*/, '').replace(/\s*[<$]$/, '').trim();
  */
 export function checkI18n(root, ignoreDirs, label, opts) {
   const start = performance.now();
+
   const srcFiles = findFiles(root, ['.js'], ignoreDirs, root).filter(
     (f) =>
       f.startsWith('src/') &&
@@ -38,39 +37,13 @@ export function checkI18n(root, ignoreDirs, label, opts) {
       !f.endsWith('.test.js'),
   );
 
-  let usesT = 0,
-    usesMsg = 0,
-    usesLocalize = 0,
-    hasInit = false,
-    hardcodedHits = 0,
-    templateFiles = 0;
-  /** @type {Array<{file: string, text: string, line: number}>} */
-  const verboseHits = [];
-
+  let usesT = 0, usesMsg = 0, usesLocalize = 0, hasInit = false;
   for (const file of srcFiles) {
     const src = readFileSync(resolve(root, file), 'utf-8');
     if (T_RE.test(src)) usesT++;
     if (MSG_RE.test(src)) usesMsg++;
     if (LOC_RE.test(src)) usesLocalize++;
     if (/router\/index|app.*init|main\.js/.test(file) && INIT_RE.test(src)) hasInit = true;
-    const templates = src.match(TPL_RE);
-    if (templates) {
-      templateFiles++;
-      for (const tpl of templates) {
-        const hits = tpl.match(PROSE_RE);
-        if (hits) {
-          hardcodedHits += hits.length;
-          if (opts?.verbose) {
-            for (const h of hits) {
-              const text = cleanHit(h);
-              const idx = src.indexOf(text);
-              const line = idx >= 0 ? src.slice(0, idx).split('\n').length : 0;
-              verboseHits.push({ file, text, line });
-            }
-          }
-        }
-      }
-    }
   }
 
   const localesDir = existsSync(resolve(root, 'src/locales'))
@@ -79,11 +52,11 @@ export function checkI18n(root, ignoreDirs, label, opts) {
       ? resolve(root, 'locales')
       : null;
 
-  const localeFiles = localesDir
-    ? readdirSync(localesDir).filter((f) => f.endsWith('.json') && f !== 'overrides.json')
-    : [];
-  const languages = localeFiles.map((f) => f.replace(/\.json$/, '').replace(/^overrides\./, ''));
   const hasOverrides = localesDir ? existsSync(resolve(localesDir, 'overrides.json')) : false;
+  const extracted = tryHybridsExtract(root);
+  const extractedKeys = extracted ? Object.keys(extracted) : null;
+  const locales = loadLocales(localesDir);
+  const languages = locales.map((l) => l.lang);
 
   const patternParts = [
     usesT ? `t() \u00d7${usesT}` : '',
@@ -92,24 +65,57 @@ export function checkI18n(root, ignoreDirs, label, opts) {
   ].filter(Boolean);
 
   const time = elapsed(start);
+
   if (!opts?.quiet) {
     const icon = patternParts.length ? '\u2705' : '\u26a0\ufe0f ';
     const pattern = patternParts.length ? patternParts.join(', ') : 'none detected';
     const langs = languages.length ? languages.join(', ') : 'en only';
     const init = `${hasInit ? 'yes' : 'not detected'} \u00b7 Overrides: ${hasOverrides ? 'yes' : 'no'} \u00b7 Languages: ${langs}`;
-    const unwrapped = hardcodedHits > 0 ? `\n     Unwrapped: ~${hardcodedHits} prose strings across ${templateFiles} template files` : '';
-    console.log(`  ${icon} ${label} (${time})\n     Pattern:   ${pattern}\n     Init:      ${init}${unwrapped}`);
-    if (opts?.verbose && verboseHits.length) {
-      console.log('');
-      const byFile = {};
-      for (const v of verboseHits) {
-        (byFile[v.file] ||= []).push(v);
+
+    let coverage = '';
+    if (extractedKeys && locales.length) {
+      const total = extractedKeys.length;
+      for (const loc of locales) {
+        const translated = extractedKeys.filter((k) => loc.keys.has(k)).length;
+        const pct = total > 0 ? Math.round((translated / total) * 100) : 0;
+        const missing = total - translated;
+        coverage += `\n     ${loc.lang}: ${translated}/${total} (${pct}%)${missing > 0 ? ` \u2014 ${missing} missing` : ' \u2714'}`;
       }
-      for (const [file, entries] of Object.entries(byFile)) {
-        console.log(`     ${file}`);
-        for (const e of entries) {
-          const truncated = e.text.length > 60 ? e.text.slice(0, 60) + '\u2026' : e.text;
-          console.log(`       L${e.line || '?'} ${truncated}`);
+    } else if (extractedKeys) {
+      coverage = `\n     Extracted: ${extractedKeys.length} translatable strings`;
+    }
+
+    let unwrapped = '';
+    if (!extractedKeys) {
+      let hardcodedHits = 0, templateFiles = 0;
+      for (const file of srcFiles) {
+        const src = readFileSync(resolve(root, file), 'utf-8');
+        const templates = src.match(TPL_RE);
+        if (templates) {
+          templateFiles++;
+          for (const tpl of templates) {
+            const hits = tpl.match(PROSE_RE);
+            if (hits) hardcodedHits += hits.length;
+          }
+        }
+      }
+      if (hardcodedHits > 0) {
+        unwrapped = `\n     Unwrapped: ~${hardcodedHits} prose strings across ${templateFiles} template files`;
+      }
+    }
+
+    console.log(`  ${icon} ${label} (${time})\n     Pattern:   ${pattern}\n     Init:      ${init}${coverage}${unwrapped}`);
+
+    if (opts?.verbose && extractedKeys && locales.length) {
+      for (const loc of locales) {
+        const missing = extractedKeys.filter((k) => !loc.keys.has(k));
+        if (missing.length) {
+          console.log(`\n     Missing in ${loc.lang} (${missing.length}):`);
+          for (const k of missing.slice(0, 50)) {
+            const truncated = k.length > 70 ? k.slice(0, 70) + '\u2026' : k;
+            console.log(`       \u2022 ${truncated}`);
+          }
+          if (missing.length > 50) console.log(`       \u2026 and ${missing.length - 50} more`);
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -12,6 +12,10 @@
     "templates/",
     "docs/"
   ],
+  "exports": {
+    ".": "./lib/check.js",
+    "./lib/*": "./lib/*"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/techninja/clearstack.git"