@techninja/clearstack 0.4.1 → 0.4.4

package/lib/check.js

@@ -14,7 +14,31 @@ export { checkFileLines, runCmd, countFiles, findFiles, elapsed, checkImports }
 export { checkI18n } from './spec-i18n.js';
 export { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
-/** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
+/**
+ * Load project-level spec extensions from `clearstack.spec.js` in the project root.
+ * The file may export a default array of Check objects. Any check whose key matches
+ * a built-in check replaces it; new keys are appended.
+ * @param {string} projectDir
+ * @returns {Promise<Check[]>}
+ */
+async function loadExtensions(projectDir) {
+  const extPath = resolve(projectDir, 'clearstack.spec.js');
+  if (!existsSync(extPath)) return [];
+  try {
+    const mod = await import(extPath);
+    const exts = mod.default ?? [];
+    if (!Array.isArray(exts)) {
+      console.warn('⚠ clearstack.spec.js default export must be an array — extensions ignored');
+      return [];
+    }
+    return exts;
+  } catch (e) {
+    console.warn(`⚠ Failed to load clearstack.spec.js: ${e.message}`);
+    return [];
+  }
+}
+
+/** @typedef {{ key: string, name: string, parent?: string, run: (opts?: object) => boolean }} Check */
 
 /** Find all jsconfig.json files — main config + subdirectories. */
 function findTypeConfigs(dir, runner) {
@@ -34,14 +58,15 @@ function findTypeConfigs(dir, runner) {
 
 /**
  * Build the unified checks array. Children have a `parent` key.
- * @returns {Check[]}
+ * Extensions from clearstack.spec.js are merged in: same key = replace, new key = append.
+ * @returns {Promise<Check[]>}
  */
-export function buildChecks(dir, cfg, cmds) {
+export async function buildChecks(dir, cfg, cmds) {
   const js = () => countFiles(dir, ['.js'], cfg.ignore);
   const css = () => countFiles(dir, ['.css'], cfg.ignore);
   const md = () => countFiles(dir, ['.md'], cfg.ignore);
   const runner = detectRunner(dir);
-  return [
+  const builtin = [
     { key: 'es', name: 'ESLint', parent: 'lint',
       run: () => runCmd('ESLint', cmds.lint, dir, `${js()} files`).pass },
     { key: 'css', name: 'Stylelint', parent: 'lint',
@@ -53,7 +78,7 @@ export function buildChecks(dir, cfg, cmds) {
     { key: 'lines', name: `Code (max ${cfg.codeMax} lines)`, parent: 'code',
       run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`, { exclude: cfg.testPattern }).pass },
     { key: 'i18n', name: 'i18n readiness', parent: 'code',
-      run: () => checkI18n(dir, cfg.ignore, 'i18n readiness').pass },
+      run: (runOpts) => checkI18n(dir, cfg.ignore, 'i18n readiness', runOpts).pass },
     { key: 'tests', name: `Tests (max ${cfg.testMax} lines)`,
       run: () => checkFileLines(dir, cfg.codeExt, cfg.testMax, cfg.ignore, `Tests (max ${cfg.testMax} lines)`, { include: cfg.testPattern }).pass },
     { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
@@ -64,6 +89,10 @@ export function buildChecks(dir, cfg, cmds) {
     { key: 'audit', name: 'Security audit',
       run: () => runCmd('Security audit', cmds.audit, dir).pass },
   ];
+  const extensions = await loadExtensions(dir);
+  if (!extensions.length) return builtin;
+  const extKeys = new Set(extensions.map((e) => e.key));
+  return [...builtin.filter((c) => !extKeys.has(c.key)), ...extensions];
 }
 
 /** Resolve a scope like 'lint', 'lint es', or 'code' to runnable check(s). */
@@ -85,10 +114,10 @@ export function parentKeys(checks) {
 }
 
 /** Run the full spec compliance check (used by clearstack CLI and scripts/spec.js). */
-export async function check(projectDir, scope) {
+export async function check(projectDir, scope, opts) {
   const cfg = loadConfig(projectDir);
   const cmds = buildCmds(projectDir);
-  const checks = buildChecks(projectDir, cfg, cmds);
+  const checks = await buildChecks(projectDir, cfg, cmds);
 
   if (scope && scope !== 'all') {
     const matched = resolveChecks(checks, scope);
@@ -98,13 +127,13 @@ export async function check(projectDir, scope) {
       console.log(`Available: ${[...tops, ...parentKeys(checks)].join(', ')}`);
       process.exit(1);
     }
-    const ok = matched.every((c) => c.run());
+    const ok = matched.every((c) => c.run(opts));
     if (!ok) process.exit(1);
     return;
   }
 
   console.log('🔍 Clearstack compliance checking now... 💙\n');
-  const results = checks.map((c) => c.run());
+  const results = checks.map((c) => c.run(opts));
   const passed = results.filter(Boolean).length;
   console.log(`\n${'='.repeat(40)}`);
   console.log(`${passed}/${results.length} checks passed.`);

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 */
 
@@ -22,11 +23,12 @@ const TPL_RE = /html`[\s\S]*?`/g;
  * @param {string} root
  * @param {string[]} ignoreDirs
  * @param {string} label
- * @param {{ quiet?: boolean }} [opts]
+ * @param {{ quiet?: boolean, verbose?: boolean }} [opts]
  * @returns {CheckResult}
  */
 export function checkI18n(root, ignoreDirs, label, opts) {
   const start = performance.now();
+
   const srcFiles = findFiles(root, ['.js'], ignoreDirs, root).filter(
     (f) =>
       f.startsWith('src/') &&
@@ -35,27 +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;
-
+  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;
-      }
-    }
   }
 
   const localesDir = existsSync(resolve(root, 'src/locales'))
@@ -64,26 +52,73 @@ 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() ×${usesT}` : '',
-    usesMsg ? `msg\` ×${usesMsg}` : '',
-    usesLocalize ? `localize() ×${usesLocalize}` : '',
+    usesT ? `t() \u00d7${usesT}` : '',
+    usesMsg ? `msg\` \u00d7${usesMsg}` : '',
+    usesLocalize ? `localize() \u00d7${usesLocalize}` : '',
   ].filter(Boolean);
 
   const time = elapsed(start);
+
   if (!opts?.quiet) {
-    const icon = patternParts.length ? '✅' : '⚠️ ';
+    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'} · Overrides: ${hasOverrides ? 'yes' : 'no'} · 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}`);
+    const init = `${hasInit ? 'yes' : 'not detected'} \u00b7 Overrides: ${hasOverrides ? 'yes' : 'no'} \u00b7 Languages: ${langs}`;
+
+    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'}`;
+      }
+    } 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`);
+        }
+      }
+    }
   }
 
   return { pass: true, label, time };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.4.1",
+  "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"