next-tongue 0.9.7 → 0.9.8

package/dist/cli/check-types.d.ts

@@ -1,4 +1,4 @@
-export type CheckKind = 'missing' | 'unused' | 'undefined' | 'mismatch' | 'syntax' | 'stale' | 'a11y' | 'bidi' | 'length' | 'duplicate';
+export type CheckKind = 'missing' | 'unused' | 'undefined' | 'dynamic' | 'mismatch' | 'syntax' | 'stale' | 'a11y' | 'bidi' | 'length' | 'duplicate' | 'icu';
 export type CheckSeverity = 'error' | 'warn';
 export type CheckIssue = {
     check: CheckKind;

package/dist/cli/extract.js

@@ -3,7 +3,7 @@ import * as readline from 'node:readline';
 import { loadConfig } from '../config/load-config.js';
 import { buildMessages } from '../compiler/build.js';
 import { loadLocaleMessages, resolveMessagePath } from '../compiler/load-messages.js';
-import { scanReferencedKeys } from '../compiler/scan-keys.js';
+import { DEFAULT_SCAN_ROOTS, scanReferencedKeys, } from '../compiler/scan-keys.js';
 import { TongueError } from '../errors.js';
 export async function cmdExtract(opts) {
     const { config, cwd } = await loadConfig({
@@ -15,7 +15,9 @@ export async function cmdExtract(opts) {
     }
     const roots = opts.include
         ? opts.include.split(',').map((s) => s.trim()).filter(Boolean)
-        : ['app', 'src', 'components'];
+        : config.scan.include.length > 0
+            ? [...config.scan.include]
+            : [...DEFAULT_SCAN_ROOTS];
     const refs = await scanReferencedKeys(cwd, roots);
     const used = new Set(refs.map((r) => r.fullKey));
     const catalogs = await loadLocaleMessages(config, cwd);

package/dist/compiler/build.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { mkdir, readFile, rename, writeFile, rm } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { TongueError } from '../errors.js';
 import { collectArgs } from './ast.js';
@@ -16,7 +16,9 @@ import { scanAppRoutes } from './scan-routes.js';
 import { loadAndMergeSources, writeSourcesCache } from './sources.js';
 export async function buildMessages(options) {
     const { config, cwd } = options;
-    const outDir = resolve(cwd, config.outDir);
+    /** Final `.tongue` path; may briefly point at a staging dir while writing. */
+    let outDir = resolve(cwd, config.outDir);
+    const publishedOutDir = outDir;
     const fileCatalogs = await loadLocaleMessages(config, cwd);
     const { catalogs, payloads: sourcePayloads } = await loadAndMergeSources(config, cwd, fileCatalogs);
     const defaultCatalog = catalogs[config.defaultLocale];
@@ -111,7 +113,8 @@ export async function buildMessages(options) {
     const defaultMsgRel = config.messages.replaceAll('{locale}', config.defaultLocale);
     const emitLocales = localesForEmit(config);
     // Content hash for idempotency (bump CODEGEN_VERSION when emit format changes)
-    const CODEGEN_VERSION = 7;
+    // Bump when emit shape changes (incl. reserved-key ident sanitization).
+    const CODEGEN_VERSION = 8;
     const hash = createHash('sha256')
         .update(JSON.stringify({
         codegen: CODEGEN_VERSION,
@@ -138,11 +141,15 @@ export async function buildMessages(options) {
             /* rebuild */
         }
     }
-    await rm(outDir, { recursive: true, force: true });
+    // Write into a staging dir, then atomically replace `.tongue` (avoids ENOTEMPTY
+    // when the previous tree is partially locked by the bundler / another build).
+    const staging = `${publishedOutDir}.tmp-${process.pid}`;
+    await clearOutputDir(staging);
+    outDir = staging;
     await mkdir(join(outDir, 'msg'), { recursive: true });
     await mkdir(join(outDir, 'ns'), { recursive: true });
     if (sourcePayloads.length) {
-        await writeSourcesCache(cwd, config.outDir, sourcePayloads);
+        await writeSourcesCache(cwd, staging, sourcePayloads);
     }
     // Shared rich-text helpers (imported by per-key modules that contain tags)
     await writeFile(join(outDir, 'rich.js'), [
@@ -398,9 +405,17 @@ export async function buildMessages(options) {
         ])),
     };
     await writeFile(join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
-    await writeFile(hashPath, hash, 'utf8');
+    await writeFile(join(outDir, '.hash'), hash, 'utf8');
     // package.json imports helper note — apps map "#tongue/*" themselves / via withTongue
     await writeFile(join(outDir, 'README.md'), 'Generated by next-tongue. Do not edit. Map `#tongue/*` → this directory.\nImport `#tongue/runtime` and call `ensureTongue()` once per process.\n', 'utf8');
+    await clearOutputDir(publishedOutDir);
+    try {
+        await rename(outDir, publishedOutDir);
+    }
+    catch (err) {
+        throw new TongueError('TONGUE_E_IO', `Cannot publish ${publishedOutDir} from staging (${err instanceof Error ? err.message : err}). Delete ${publishedOutDir} and any \`${config.outDir}.tmp-*\` dirs, then re-run tongue build.`, { file: publishedOutDir });
+    }
+    outDir = publishedOutDir;
     return {
         outDir,
         locales: emitLocales,
@@ -409,6 +424,34 @@ export async function buildMessages(options) {
         hash,
     };
 }
+/** Remove a directory tree; on ENOTEMPTY/EBUSY, retry then rename-aside. */
+async function clearOutputDir(path) {
+    for (let i = 0; i < 6; i++) {
+        try {
+            await rm(path, { recursive: true, force: true });
+            return;
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code !== 'ENOTEMPTY' && code !== 'EBUSY' && code !== 'EPERM') {
+                if (code === 'ENOENT')
+                    return;
+                throw err;
+            }
+            await new Promise((r) => setTimeout(r, 40 * (i + 1)));
+        }
+    }
+    const trash = `${path}.trash-${process.pid}-${Date.now()}`;
+    try {
+        await rename(path, trash);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return;
+        throw new TongueError('TONGUE_E_IO', `Cannot clear ${path} (${err instanceof Error ? err.message : err}). Delete it manually and re-run tongue build.`, { file: path });
+    }
+    void rm(trash, { recursive: true, force: true }).catch(() => { });
+}
 /** Locales written into message modules / types (includes pseudo when enabled). */
 export function localesForEmit(config) {
     if (!config.pseudo || config.pseudo.enabled === false)

package/dist/compiler/codegen/emit-js.d.ts

@@ -26,5 +26,5 @@ export declare function emitRichMessageFunction(exportName: string, ast: Message
 }): string;
 /** True when the AST contains at least one rich tag. */
 export declare function hasTags(ast: MessageAst): boolean;
-/** Safe JS identifier from a message key. */
+/** Safe JS identifier from a message key (e.g. `continue` → `continue_`). */
 export declare function safeIdent(key: string): string;

package/dist/compiler/codegen/emit-js.js

@@ -342,10 +342,65 @@ function stringifyAstAsConstant(ast) {
     }
     return out;
 }
-/** Safe JS identifier from a message key. */
+/** ECMAScript reserved words / strict-mode reserved — unsafe as bare identifiers. */
+const RESERVED_IDENTS = new Set([
+    'arguments',
+    'await',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'continue',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'eval',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'instanceof',
+    'interface',
+    'let',
+    'new',
+    'null',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'return',
+    'static',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+/** Safe JS identifier from a message key (e.g. `continue` → `continue_`). */
 export function safeIdent(key) {
-    const cleaned = key.replace(/[^A-Za-z0-9_]/g, '_');
+    let cleaned = key.replace(/[^A-Za-z0-9_]/g, '_');
+    if (!cleaned)
+        cleaned = '_';
     if (/^[0-9]/.test(cleaned))
-        return `_${cleaned}`;
-    return cleaned || '_';
+        cleaned = `_${cleaned}`;
+    if (RESERVED_IDENTS.has(cleaned))
+        cleaned = `${cleaned}_`;
+    return cleaned;
 }

package/dist/compiler/scan-keys.d.ts

@@ -5,6 +5,13 @@ export type ReferencedKey = {
     file: string;
     line: number;
 };
+export type UndeclaredDynamic = {
+    file: string;
+    line: number;
+    /** Translator binding, e.g. `t` */
+    name: string;
+    namespace: string;
+};
 export type ScanResult = {
     refs: ReferencedKey[];
     /**
@@ -12,13 +19,20 @@ export type ScanResult = {
      * unused-key warnings for these namespaces are suppressed.
      */
     dynamicNamespaces: Set<string>;
+    /**
+     * Client `useT` + `t(variable)` without `t.dynamic` — runtime stub will throw.
+     * Server `getT` non-literals are OK (whole namespace is loaded).
+     */
+    undeclaredDynamics: UndeclaredDynamic[];
 };
+/** Default directories scanned by `tongue check` / `extract`. */
+export declare const DEFAULT_SCAN_ROOTS: readonly ["app", "src", "components", "lib", "server", "actions"];
 /**
  * Find `t('key')` / `t.rich('key')` under a known `useT`/`getT` namespace,
  * plus `t.dynamic(..., { from })` declared keys and dynamic `t(var)` markers.
  */
-export declare function scanReferencedKeys(cwd: string, roots?: string[]): Promise<ReferencedKey[]>;
-export declare function scanKeys(cwd: string, roots?: string[]): Promise<ScanResult>;
+export declare function scanReferencedKeys(cwd: string, roots?: readonly string[]): Promise<ReferencedKey[]>;
+export declare function scanKeys(cwd: string, roots?: readonly string[]): Promise<ScanResult>;
 /** Strip // and /* *\/ comments; preserve newlines for line numbers. */
 export declare function stripComments(source: string): string;
 export declare function extractFromSource(source: string, file: string): ScanResult;

package/dist/compiler/scan-keys.js

@@ -1,6 +1,15 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { findDynamicCalls } from './dynamic-from.js';
+/** Default directories scanned by `tongue check` / `extract`. */
+export const DEFAULT_SCAN_ROOTS = [
+    'app',
+    'src',
+    'components',
+    'lib',
+    'server',
+    'actions',
+];
 const SOURCE_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mdx']);
 const SKIP_DIRS = new Set([
     'node_modules',
@@ -15,10 +24,10 @@ const SKIP_DIRS = new Set([
  * Find `t('key')` / `t.rich('key')` under a known `useT`/`getT` namespace,
  * plus `t.dynamic(..., { from })` declared keys and dynamic `t(var)` markers.
  */
-export async function scanReferencedKeys(cwd, roots = ['app', 'src', 'components']) {
+export async function scanReferencedKeys(cwd, roots = DEFAULT_SCAN_ROOTS) {
     return (await scanKeys(cwd, roots)).refs;
 }
-export async function scanKeys(cwd, roots = ['app', 'src', 'components']) {
+export async function scanKeys(cwd, roots = DEFAULT_SCAN_ROOTS) {
     const files = [];
     for (const root of roots) {
         const abs = join(cwd, root);
@@ -33,6 +42,7 @@ export async function scanKeys(cwd, roots = ['app', 'src', 'components']) {
     }
     const refs = [];
     const dynamicNamespaces = new Set();
+    const undeclaredDynamics = [];
     for (const file of files) {
         const src = await readFile(file, 'utf8');
         const rel = relative(cwd, file);
@@ -40,8 +50,9 @@ export async function scanKeys(cwd, roots = ['app', 'src', 'components']) {
         refs.push(...part.refs);
         for (const ns of part.dynamicNamespaces)
             dynamicNamespaces.add(ns);
+        undeclaredDynamics.push(...part.undeclaredDynamics);
     }
-    return { refs, dynamicNamespaces };
+    return { refs, dynamicNamespaces, undeclaredDynamics };
 }
 async function walk(dir, out) {
     const entries = await readdir(dir, { withFileTypes: true });
@@ -129,12 +140,16 @@ export function extractFromSource(source, file) {
     const code = stripComments(source);
     const out = [];
     const dynamicNamespaces = new Set();
-    const translators = new Map(); // var → ns
+    const undeclaredDynamics = [];
+    const translators = new Map();
     // useT('ns') | getT('ns') | getT(locale, 'ns')
-    const declRe = /(?:const|let|var)\s+(\w+)\s*=\s*(?:await\s+)?(?:useT|getT)\s*\(\s*(?:[^'"\n,]+,\s*)?(['"])([^'"]*)\2\s*\)/g;
+    const declRe = /(?:const|let|var)\s+(\w+)\s*=\s*(?:await\s+)?(useT|getT)\s*\(\s*(?:[^'"\n,]+,\s*)?(['"])([^'"]*)\3\s*\)/g;
     let m;
     while ((m = declRe.exec(code)) !== null) {
-        translators.set(m[1], m[3] || '_root');
+        translators.set(m[1], {
+            ns: m[4] || '_root',
+            kind: m[2],
+        });
     }
     const push = (ns, key, index) => {
         const fullKey = ns === '_root' || ns === '' ? key : `${ns}.${key}`;
@@ -146,7 +161,7 @@ export function extractFromSource(source, file) {
             line: lineAt(code, index),
         });
     };
-    for (const [varName, ns] of translators) {
+    for (const [varName, { ns, kind }] of translators) {
         // Literal t('key') / t.rich('key')
         const callRe = new RegExp(`\\b${escapeRegExp(varName)}(?:\\.rich)?\\s*\\(\\s*(['"])([^'"]+)\\1`, 'g');
         let cm;
@@ -168,14 +183,28 @@ export function extractFromSource(source, file) {
         while ((nm = nsRe.exec(code)) !== null) {
             dynamicNamespaces.add(nm[2] || '_root');
         }
-        // Non-literal t(var) — suppress unused for the namespace only.
+        // Non-literal t(var) — suppress unused for the namespace.
+        // Client useT stubs throw — report each site. Server getT is fine.
         // Do NOT harvest unrelated string arrays (cache tags, sort keys, …).
         const nonLitRe = new RegExp(`\\b${escapeRegExp(varName)}(?:\\.rich)?\\s*\\(\\s*(?!['"])([A-Za-z_$][\\w$]*)`, 'g');
-        if (nonLitRe.test(code)) {
+        let nl;
+        let sawNonLit = false;
+        while ((nl = nonLitRe.exec(code)) !== null) {
+            sawNonLit = true;
+            if (kind === 'useT') {
+                undeclaredDynamics.push({
+                    file,
+                    line: lineAt(code, nl.index),
+                    name: varName,
+                    namespace: ns || '_root',
+                });
+            }
+        }
+        if (sawNonLit) {
             dynamicNamespaces.add(ns || '_root');
         }
     }
-    return { refs: out, dynamicNamespaces };
+    return { refs: out, dynamicNamespaces, undeclaredDynamics };
 }
 function lineAt(source, index) {
     let line = 1;

package/dist/compiler/validate/catalog.d.ts

@@ -20,3 +20,5 @@ export type TongueLock = {
 export declare function validateStale(config: ResolvedTongueConfig, cwd: string, opts?: {
     locales?: readonly string[];
 }): Promise<CheckIssue[]>;
+/** Letter + single quote + letter — usually meant as prose apostrophe, not ICU quote. */
+export declare function likelyUnescapedApostrophe(icu: string): boolean;

package/dist/compiler/validate/catalog.js

@@ -69,6 +69,17 @@ export async function validateCatalog(config, cwd, opts) {
                 });
                 continue;
             }
+            if (likelyUnescapedApostrophe(source)) {
+                issues.push({
+                    check: 'icu',
+                    severity: 'warn',
+                    message: `Key "${fullKey}" looks like a natural-language apostrophe (e.g. French). In ICU, double it: "l''été" → l'été`,
+                    key: fullKey,
+                    locale: config.defaultLocale,
+                    file,
+                    ...(line != null ? { line } : {}),
+                });
+            }
             const defaultArgs = collectArgs(defaultAst);
             for (const locale of locales) {
                 if (locale === config.defaultLocale)
@@ -224,3 +235,15 @@ export async function validateStale(config, cwd, opts) {
     }
     return issues;
 }
+/** Letter + single quote + letter — usually meant as prose apostrophe, not ICU quote. */
+export function likelyUnescapedApostrophe(icu) {
+    for (let i = 0; i < icu.length - 2; i++) {
+        const a = icu[i];
+        const b = icu[i + 1];
+        const c = icu[i + 2];
+        if (b === "'" && /[A-Za-zÀ-ÿ]/.test(a) && /[A-Za-zÀ-ÿ]/.test(c)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/compiler/validate/usage.d.ts

@@ -1,4 +1,4 @@
 import type { ResolvedTongueConfig } from '../../config/types.js';
 import type { CheckIssue } from '../../cli/check-types.js';
-/** unused + undefined checks against scanned source references. */
+/** unused + undefined + undeclared client dynamic checks against scanned source. */
 export declare function validateUsage(config: ResolvedTongueConfig, cwd: string): Promise<CheckIssue[]>;

package/dist/compiler/validate/usage.js

@@ -1,5 +1,5 @@
 import { loadLocaleMessages } from '../load-messages.js';
-import { scanKeys } from '../scan-keys.js';
+import { DEFAULT_SCAN_ROOTS, scanKeys } from '../scan-keys.js';
 function severityFor(level, alwaysError = false) {
     if (alwaysError)
         return 'error';
@@ -11,7 +11,26 @@ function namespaceOf(fullKey) {
     const i = fullKey.indexOf('.');
     return i === -1 ? '_root' : fullKey.slice(0, i);
 }
-/** unused + undefined checks against scanned source references. */
+/** Glob-lite: `*` matches any substring (e.g. `common.*`, `*.seeAll`). */
+function matchesIgnore(fullKey, patterns) {
+    for (const raw of patterns) {
+        const p = raw.trim();
+        if (!p)
+            continue;
+        if (p === fullKey)
+            return true;
+        if (!p.includes('*'))
+            continue;
+        const re = new RegExp(`^${p
+            .split('*')
+            .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+            .join('.*')}$`);
+        if (re.test(fullKey))
+            return true;
+    }
+    return false;
+}
+/** unused + undefined + undeclared client dynamic checks against scanned source. */
 export async function validateUsage(config, cwd) {
     const issues = [];
     const catalogs = await loadLocaleMessages(config, cwd);
@@ -24,7 +43,8 @@ export async function validateUsage(config, cwd) {
             defined.add(ns === '_root' ? key : `${ns}.${key}`);
         }
     }
-    const { refs, dynamicNamespaces } = await scanKeys(cwd);
+    const roots = config.scan.include.length > 0 ? config.scan.include : DEFAULT_SCAN_ROOTS;
+    const { refs, dynamicNamespaces, undeclaredDynamics } = await scanKeys(cwd, roots);
     const used = new Set();
     for (const ref of refs) {
         used.add(ref.fullKey);
@@ -39,11 +59,23 @@ export async function validateUsage(config, cwd) {
             });
         }
     }
+    for (const site of undeclaredDynamics) {
+        issues.push({
+            check: 'dynamic',
+            severity: 'error',
+            message: `useT('${site.namespace}') ${site.name}(variable) is not a string literal — use ${site.name}.dynamic(key, { from: [...] }) so the loader can import keys (plain ${site.name}(var) throws at runtime on the client)`,
+            file: site.file,
+            line: site.line,
+        });
+    }
     const unusedSev = severityFor(config.strict.unused);
     if (unusedSev) {
+        const ignore = config.strict.unusedIgnore;
         for (const fullKey of defined) {
             if (used.has(fullKey))
                 continue;
+            if (matchesIgnore(fullKey, ignore))
+                continue;
             // Dynamic t(var) / t.ns / t.dynamic — do not false-flag catalog keys as unused
             if (dynamicNamespaces.has(namespaceOf(fullKey)))
                 continue;

package/dist/config/types.d.ts

@@ -55,9 +55,18 @@ export type TongueConfig = {
         list?: Record<string, Intl.ListFormatOptions>;
     };
     outDir?: string;
+    /**
+     * Directories scanned by `tongue check` / `extract` for `getT`/`useT` call sites.
+     * Defaults to app, src, components, lib, server, actions.
+     */
+    scan?: {
+        include?: string[];
+    };
     strict?: {
         missing?: StrictLevel;
         unused?: StrictLevel;
+        /** Full keys or globs (`common.*`) excluded from unused warnings. */
+        unusedIgnore?: string[];
         mismatch?: StrictLevel;
         a11y?: StrictLevel;
         bidi?: StrictLevel;
@@ -102,9 +111,13 @@ export type ResolvedTongueConfig = {
         list: Record<string, Intl.ListFormatOptions>;
     };
     outDir: string;
+    scan: {
+        include: readonly string[];
+    };
     strict: {
         missing: StrictLevel;
         unused: StrictLevel;
+        unusedIgnore: readonly string[];
         mismatch: StrictLevel;
         a11y: StrictLevel;
         bidi: StrictLevel;

package/dist/config/validate.js

@@ -127,9 +127,13 @@ export function resolveConfig(input) {
             list: input.formats?.list ?? {},
         },
         outDir: input.outDir ?? '.tongue',
+        scan: {
+            include: input.scan?.include ?? [],
+        },
         strict: {
             missing: input.strict?.missing ?? 'error',
             unused: input.strict?.unused ?? 'warn',
+            unusedIgnore: input.strict?.unusedIgnore ?? [],
             mismatch: input.strict?.mismatch ?? 'error',
             a11y: input.strict?.a11y ?? 'error',
             bidi: input.strict?.bidi ?? 'warn',

package/dist/next/loader.js

@@ -12,6 +12,7 @@
  * Escape analysis: if `t` is passed around, falls back to namespace import + warning.
  */
 import { findDynamicCalls } from '../compiler/dynamic-from.js';
+import { safeIdent } from '../compiler/codegen/emit-js.js';
 const USE_T_DECL = /(?:const|let|var)\s+(\w+)\s*=\s*useT\s*\(\s*(['"])([^'"]*)\2\s*\)/g;
 export function transformCallSites(source, resourcePath, _options = {}) {
     const warnings = [];
@@ -181,8 +182,7 @@ function safeImportIdent(ns, key) {
     return `__tongue_${(ns + '_' + key).replace(/[^A-Za-z0-9_]/g, '_')}`;
 }
 function safeExport(key) {
-    const cleaned = key.replace(/[^A-Za-z0-9_]/g, '_');
-    return /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned || '_';
+    return safeIdent(key);
 }
 /** Webpack/Turbopack loader entry. */
 export default function tongueLoader(source) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-tongue",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "Compiler-first, type-safe i18n for the Next.js 16 App Router",
   "license": "MIT",
   "type": "module",