baldart 4.50.0 → 4.52.0

package/src/commands/doctor.js

@@ -34,6 +34,7 @@ const GitHooks = require('../utils/githooks');
 const LspInstaller = require('../utils/lsp-installer');
 const GraphifyInstaller = require('../utils/graphify-installer');
 const ToolchainInstaller = require('../utils/toolchain-installer');
+const I18nGate = require('../utils/i18n-gate');
 const ToolCurrency = require('../utils/tool-currency');
 const CodexOrphans = require('../utils/codex-orphans');
 const UpdateNotifier = require('../utils/update-notifier');
@@ -425,6 +426,29 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on toolchain probe */ }
 
+    // ---- i18n layer (since v4.52.0) ------------------------------------
+    // Detection-only backfill: the i18n framework is the consumer's, so doctor
+    // never installs it — it flags a missing context registry and a missing
+    // anti-hardcoded lint plugin (the only thing BALDART offers to install).
+    state.i18nEnabled = false;
+    state.i18nRegistryMissing = false;
+    state.i18nGateMissing = false;
+    try {
+      if (config && !config.__malformed && config.features && config.features.has_i18n === true) {
+        state.i18nEnabled = true;
+        const regPath = (config.paths && config.paths.i18n_registry) || '';
+        if (regPath && !fs.existsSync(path.join(cwd, regPath))) {
+          state.i18nRegistryMissing = true;
+        }
+        // Deterministic anti-hardcoded gate present? (standalone config + deps).
+        // Only meaningful for a JS/TS project — skip the gate check otherwise.
+        if (I18nGate.hasPackageJson(cwd)
+          && (!I18nGate.isConfigPresent(cwd) || !I18nGate.depsInstalled(cwd))) {
+          state.i18nGateMissing = true;
+        }
+      }
+    } catch (_) { /* never block doctor on i18n probe */ }
+
     // ---- External-tool version currency (since v4.38.0) ----------------
     // BALDART pins none of the external tools it installs (graphifyy via pipx,
     // language servers via npm/system) — pipx/npm never auto-upgrade, so a
@@ -885,6 +909,40 @@ function planActions(state) {
     });
   }
 
+  // ---- i18n layer backfill (since v4.52.0) ----------------------------
+  // Detection-only: BALDART never installs the consumer's i18n framework. It
+  // offers to install the anti-hardcoded lint plugin and flags a missing
+  // context registry (which `/i18n` or the consumer scaffolds).
+  if (state.i18nEnabled && state.i18nGateMissing) {
+    const gateDeps = I18nGate.depsFor(state.cwd);
+    const gateFile = I18nGate.configFilename(state.cwd);
+    actions.push({
+      key: 'i18n-gate-setup',
+      label: `Set up the anti-hardcoded gate (${gateDeps.join(', ')} + ${gateFile})`,
+      why: `features.has_i18n is true but the deterministic anti-hardcoded gate is not fully set up (missing devDeps or ${gateFile}), so hardcoded user-facing strings are not blocked. Installs the gate dependencies and writes a STANDALONE ESLint config (era-matched to your ESLint; works on Biome projects; never touches your main lint config).`,
+      autoOk: false, // installs devDependencies; confirm
+      run: async () => {
+        const res = I18nGate.setup(state.cwd);
+        if (res.error) { UI.warning(`Gate setup incomplete: ${res.error}.`); return; }
+        if (res.installed) UI.success(`Installed ${gateDeps.join(', ')}.`);
+        if (res.config && res.config.status === 'written') UI.success(`Wrote ${res.config.file} (${res.era} ESLint config).`);
+        UI.success(`Anti-hardcoded gate ready: \`${I18nGate.commandForCwd(state.cwd)}\`.`);
+        UI.info('If i18n.lint_command is unset in baldart.config.yml, the gate runs by convention via the config file; `baldart configure` records it explicitly.');
+      },
+    });
+  }
+  if (state.i18nEnabled && state.i18nRegistryMissing) {
+    actions.push({
+      key: 'i18n-registry-missing',
+      label: 'i18n context registry not found — scaffold it with /i18n',
+      why: `features.has_i18n is true but the context registry at paths.i18n_registry does not exist yet. It is the SSOT for per-key translation context. Run the /i18n skill (or create the YAML) to start populating it; coder STEP 9 fills it as keys are added.`,
+      autoOk: false, // informational — no safe auto-create without project context
+      run: async () => {
+        UI.info('Run `/i18n` in your editor to audit + scaffold the registry, or create the YAML at the configured path. See framework/docs/I18N-LAYER.md.');
+      },
+    });
+  }
+
   // External-tool version currency (since v4.38.0). One non-blocking upgrade
   // action per managed tool confirmed behind upstream — the tool-dependency
   // analogue of the `baldart` CLI's own UpdateNotifier. `unknown`/`current`

package/src/commands/update.js

@@ -1312,6 +1312,11 @@ async function update(options = {}, unknownArgs = []) {
             const missingToolchainCmds = Object.keys((tpl.toolchain && tpl.toolchain.commands) || {})
               .filter((k) => !(k in ((cur2.toolchain && cur2.toolchain.commands) || {})))
               .map((k) => `toolchain.commands.${k}`);
+            // `i18n:` (since v4.52.0) — same nested-block contract as `graph:` /
+            // `toolchain:`. Diff its own scalar keys so a new option surfaces.
+            const missingI18n = Object.keys(tpl.i18n || {})
+              .filter((k) => !(k in (cur2.i18n || {})))
+              .map((k) => `i18n.${k}`);
             const allMissing = [
               ...missingPaths,
               ...missingFeatures,
@@ -1320,6 +1325,7 @@ async function update(options = {}, unknownArgs = []) {
               ...missingGraph.map((k) => `graph.${k}`),
               ...missingToolchain,
               ...missingToolchainCmds,
+              ...missingI18n,
             ];
             if (allMissing.length) {
               UI.newline();

package/src/utils/i18n-gate.js

@@ -0,0 +1,195 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * i18n anti-hardcoded gate — BALDART-owned standalone ESLint config (since v4.52.0).
+ *
+ * The "no hardcoded user-facing strings" rule must be enforced DETERMINISTICALLY,
+ * regardless of the consumer's lint setup. The most-adopted rule
+ * (`eslint-plugin-i18next` `no-literal-string`) is framework-agnostic (it flags
+ * literal JSX text/attributes for next-intl / i18next / vue / any stack) BUT it is
+ * an ESLint plugin — a Biome-only toolchain (BALDART's default) does not run it,
+ * and wiring it into the user's own ESLint config is fragile.
+ *
+ * So BALDART writes a SEPARATE, self-contained config it owns and runs ESLint
+ * against it with an explicit `--config`. This never touches the user's main lint
+ * config, runs the i18n rule deterministically, and works on Biome projects (a
+ * dedicated ESLint invocation just for this gate).
+ *
+ * ESLint era matters: ESLint 9 uses FLAT config (`eslint.i18n.config.mjs`); ESLint
+ * 8 uses LEGACY rc config (`.eslintrc.i18n.json` + `--no-eslintrc`). We detect the
+ * consumer's installed/declared ESLint major and emit the matching pair so the
+ * gate command actually runs instead of erroring on every file. `mode: 'jsx-only'`
+ * is the default — it flags JSX text AND user-facing attributes (title /
+ * placeholder / alt / aria-label), matching the prose contract; non-JSX
+ * imperative strings (e.g. `toast("Saved")`) remain the code-reviewer backstop's
+ * domain. Verified against ESLint 9 + eslint-plugin-i18next: Bad.tsx (3 findings)
+ * fails, Good.tsx (t()) passes.
+ */
+const FLAT_CONFIG = 'eslint.i18n.config.mjs';
+const LEGACY_CONFIG = '.eslintrc.i18n.json';
+const MODE = 'jsx-only';
+
+const FLAT_COMMAND = `npx eslint --config ${FLAT_CONFIG} .`;
+const LEGACY_COMMAND = `npx eslint --no-eslintrc -c ${LEGACY_CONFIG} --ext .js,.jsx,.ts,.tsx .`;
+// Default advertised command (flat / ESLint 9). `resolveLintCommand` picks the
+// real one based on which config file is on disk.
+const LINT_COMMAND = FLAT_COMMAND;
+
+const FLAT_DEPS = ['eslint', 'eslint-plugin-i18next', 'typescript-eslint'];
+const LEGACY_DEPS = ['eslint', 'eslint-plugin-i18next', '@typescript-eslint/parser'];
+// Advertised set (flat). `setup` installs the era-correct one.
+const DEV_DEPS = FLAT_DEPS;
+
+const FLAT_BODY = `// BALDART-owned i18n anti-hardcoded gate (generated by \`baldart configure\` /
+// \`baldart doctor\`, since v4.52.0). STANDALONE — this file does NOT affect your
+// main ESLint setup. ESLint 9 flat config. Run via: ${FLAT_COMMAND}
+//
+// Fails when a user-facing string is hardcoded instead of routed through your i18n
+// translation function. \`mode: '${MODE}'\` flags JSX text AND user-facing
+// attributes (title/placeholder/alt/aria-label). Broaden to 'all' for non-JSX
+// strings too, or add to \`ignores\` / the rule allowlist — BALDART writes this file
+// only when absent and never overwrites your edits.
+import i18next from 'eslint-plugin-i18next';
+import tseslint from 'typescript-eslint';
+
+export default [
+  {
+    files: ['**/*.{js,jsx,ts,tsx,mjs,cjs}'],
+    ignores: [
+      '**/node_modules/**', '**/dist/**', '**/build/**', '**/.next/**',
+      '**/out/**', '**/coverage/**', '**/*.test.*', '**/*.spec.*',
+    ],
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: { ecmaFeatures: { jsx: true }, sourceType: 'module' },
+    },
+    plugins: { i18next },
+    rules: {
+      'i18next/no-literal-string': ['error', { mode: '${MODE}' }],
+    },
+  },
+];
+`;
+
+const LEGACY_BODY = JSON.stringify({
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: { ecmaFeatures: { jsx: true }, sourceType: 'module' },
+  plugins: ['i18next'],
+  rules: { 'i18next/no-literal-string': ['error', { mode: MODE }] },
+  ignorePatterns: ['node_modules/', 'dist/', 'build/', '.next/', 'out/', 'coverage/', '*.test.*', '*.spec.*'],
+}, null, 2) + '\n';
+
+function hasPackageJson(cwd = process.cwd()) {
+  return fs.existsSync(path.join(cwd, 'package.json'));
+}
+
+function readPkgDeps(cwd = process.cwd()) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  } catch { return {}; }
+}
+
+/**
+ * Detect the consumer's ESLint major. Prefers the installed version, then the
+ * declared range, then null (absent → a fresh install gets ESLint 9 → flat).
+ */
+function eslintMajor(cwd = process.cwd()) {
+  try {
+    const p = JSON.parse(fs.readFileSync(path.join(cwd, 'node_modules', 'eslint', 'package.json'), 'utf8'));
+    const m = parseInt(String(p.version).split('.')[0], 10);
+    if (!Number.isNaN(m)) return m;
+  } catch { /* not installed */ }
+  const deps = readPkgDeps(cwd);
+  if (deps.eslint) {
+    const m = String(deps.eslint).match(/(\d+)/);
+    if (m) return parseInt(m[1], 10);
+  }
+  return null;
+}
+
+/** Legacy when an EXISTING ESLint 8 is detected; flat otherwise (incl. fresh). */
+function useLegacy(cwd = process.cwd()) {
+  return eslintMajor(cwd) === 8;
+}
+
+function configFilename(cwd = process.cwd()) {
+  return useLegacy(cwd) ? LEGACY_CONFIG : FLAT_CONFIG;
+}
+
+function depsFor(cwd = process.cwd()) {
+  return useLegacy(cwd) ? LEGACY_DEPS : FLAT_DEPS;
+}
+
+/** True when EITHER era's config file is on disk. */
+function isConfigPresent(cwd = process.cwd()) {
+  return fs.existsSync(path.join(cwd, FLAT_CONFIG)) || fs.existsSync(path.join(cwd, LEGACY_CONFIG));
+}
+
+/** Write the era-correct standalone config — only when absent. Never overwrites. */
+function writeConfig(cwd = process.cwd()) {
+  const legacy = useLegacy(cwd);
+  const file = legacy ? LEGACY_CONFIG : FLAT_CONFIG;
+  const p = path.join(cwd, file);
+  if (isConfigPresent(cwd)) return { status: 'exists', path: p, file };
+  fs.writeFileSync(p, legacy ? LEGACY_BODY : FLAT_BODY, 'utf8');
+  return { status: 'written', path: p, file };
+}
+
+/** True when every era-correct gate dependency is declared in package.json. */
+function depsInstalled(cwd = process.cwd()) {
+  const deps = readPkgDeps(cwd);
+  return depsFor(cwd).every((d) => d in deps);
+}
+
+/** Install the era-correct gate dev dependencies. Throws on failure. */
+function installDeps(cwd = process.cwd()) {
+  execSync(`npm install -D ${depsFor(cwd).join(' ')}`, { cwd, stdio: 'ignore' });
+}
+
+/**
+ * Full setup: install deps (if a package.json exists) + write the era-correct
+ * config. Returns a structured result; never throws (errors are reported).
+ */
+function setup(cwd = process.cwd()) {
+  const result = { installed: false, config: null, error: null, era: useLegacy(cwd) ? 'legacy' : 'flat' };
+  try {
+    if (hasPackageJson(cwd) && !depsInstalled(cwd)) {
+      installDeps(cwd);
+      result.installed = true;
+    }
+    result.config = writeConfig(cwd);
+  } catch (e) {
+    result.error = e.message;
+  }
+  return result;
+}
+
+/**
+ * Resolve the command a gate runner should execute. Order: explicit
+ * `i18n.lint_command` from config → the on-disk standalone config (flat or
+ * legacy) by convention → null (gate SKIPs, never a silent pass).
+ */
+function resolveLintCommand(cwd = process.cwd(), config = null) {
+  const explicit = config && config.i18n && config.i18n.lint_command;
+  if (explicit) return explicit;
+  if (fs.existsSync(path.join(cwd, FLAT_CONFIG))) return FLAT_COMMAND;
+  if (fs.existsSync(path.join(cwd, LEGACY_CONFIG))) return LEGACY_COMMAND;
+  return null;
+}
+
+/** The command configure should record for this project's ESLint era. */
+function commandForCwd(cwd = process.cwd()) {
+  return useLegacy(cwd) ? LEGACY_COMMAND : FLAT_COMMAND;
+}
+
+module.exports = {
+  FLAT_CONFIG, LEGACY_CONFIG, MODE, FLAT_COMMAND, LEGACY_COMMAND, LINT_COMMAND,
+  FLAT_DEPS, LEGACY_DEPS, DEV_DEPS,
+  hasPackageJson, eslintMajor, useLegacy, configFilename, depsFor,
+  isConfigPresent, writeConfig, depsInstalled, installDeps, setup,
+  resolveLintCommand, commandForCwd,
+};