next-tongue 0.9.12 → 0.9.13

package/dist/cli/extract.js

@@ -4,6 +4,7 @@ import { loadConfig } from '../config/load-config.js';
 import { buildMessages } from '../compiler/build.js';
 import { loadLocaleMessages, resolveMessagePath } from '../compiler/load-messages.js';
 import { DEFAULT_SCAN_ROOTS, scanReferencedKeys, } from '../compiler/scan-keys.js';
+import { collectUnusedIgnores, isUnusedIgnored, matchesUnusedIgnoreGlob, } from '../compiler/unused-meta.js';
 import { TongueError } from '../errors.js';
 export async function cmdExtract(opts) {
     const { config, cwd } = await loadConfig({
@@ -28,8 +29,6 @@ export async function cmdExtract(opts) {
             defined.add(ns === '_root' ? key : `${ns}.${key}`);
         }
     }
-    const missing = [...used].filter((k) => !defined.has(k)).sort();
-    const unused = [...defined].filter((k) => !used.has(k)).sort();
     const placeholder = opts.placeholder ?? null; // null → use key as value
     const abs = resolveMessagePath(cwd, config.messages, config.defaultLocale);
     let raw;
@@ -46,6 +45,14 @@ export async function cmdExtract(opts) {
     catch (err) {
         throw new TongueError('TONGUE_E_PARSE', `Invalid JSON: ${err instanceof Error ? err.message : err}`, { file: abs });
     }
+    const metaIgnores = collectUnusedIgnores(json);
+    const configIgnores = config.strict.unusedIgnore;
+    const missing = [...used].filter((k) => !defined.has(k)).sort();
+    const unused = [...defined]
+        .filter((k) => !used.has(k))
+        .filter((k) => !isUnusedIgnored(k, metaIgnores))
+        .filter((k) => !matchesUnusedIgnoreGlob(k, configIgnores))
+        .sort();
     let added = 0;
     let pruned = 0;
     for (const fullKey of missing) {

package/dist/compiler/unused-meta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Catalog `$meta` flags that suppress `unused` (and extract `--prune`).
+ *
+ * Per key (sibling `key$meta`):
+ *   { "planned": true }
+ *   { "ignoreUnused": true }
+ *   { "@tongue-ignore": true }
+ *
+ * Per namespace (child `$meta` on the namespace object):
+ *   "common": { "$meta": { "planned": true }, "seeAll": "…" }
+ */
+export type Nested = Record<string, unknown>;
+export type UnusedIgnoreIndex = {
+    /** Exact full keys (e.g. `common.seeAll`). */
+    keys: Set<string>;
+    /** Namespace prefixes whose unused keys are ignored (`common` → `common.*`). */
+    namespaces: Set<string>;
+};
+/** Walk default-locale JSON and collect planned / @tongue-ignore markers. */
+export declare function collectUnusedIgnores(root: Nested): UnusedIgnoreIndex;
+export declare function isUnusedIgnored(fullKey: string, index: UnusedIgnoreIndex): boolean;
+/** Glob-lite for `strict.unusedIgnore` (`common.*`, `*.seeAll`). */
+export declare function matchesUnusedIgnoreGlob(fullKey: string, patterns: readonly string[]): boolean;

package/dist/compiler/unused-meta.js

@@ -0,0 +1,86 @@
+/**
+ * Catalog `$meta` flags that suppress `unused` (and extract `--prune`).
+ *
+ * Per key (sibling `key$meta`):
+ *   { "planned": true }
+ *   { "ignoreUnused": true }
+ *   { "@tongue-ignore": true }
+ *
+ * Per namespace (child `$meta` on the namespace object):
+ *   "common": { "$meta": { "planned": true }, "seeAll": "…" }
+ */
+function metaIgnoresUnused(meta) {
+    if (!meta || typeof meta !== 'object' || Array.isArray(meta))
+        return false;
+    const m = meta;
+    if (m.planned === true)
+        return true;
+    if (m.ignoreUnused === true)
+        return true;
+    if (m['@tongue-ignore'] === true)
+        return true;
+    // Allow string form: "@tongue-ignore" or "planned"
+    if (typeof m.unused === 'string') {
+        const u = m.unused.toLowerCase();
+        if (u === 'ignore' || u === 'planned' || u === '@tongue-ignore')
+            return true;
+    }
+    return false;
+}
+/** Walk default-locale JSON and collect planned / @tongue-ignore markers. */
+export function collectUnusedIgnores(root) {
+    const keys = new Set();
+    const namespaces = new Set();
+    walk(root, '', keys, namespaces);
+    return { keys, namespaces };
+}
+function walk(node, prefix, keys, namespaces) {
+    const nsMeta = node['$meta'];
+    if (prefix && metaIgnoresUnused(nsMeta)) {
+        namespaces.add(prefix);
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key === '$meta' || key.endsWith('$meta') || key.endsWith('$description')) {
+            continue;
+        }
+        const full = prefix ? `${prefix}.${key}` : key;
+        if (value != null && typeof value === 'object' && !Array.isArray(value)) {
+            walk(value, full, keys, namespaces);
+            continue;
+        }
+        if (typeof value !== 'string')
+            continue;
+        const meta = node[`${key}$meta`];
+        if (metaIgnoresUnused(meta)) {
+            keys.add(full);
+        }
+    }
+}
+export function isUnusedIgnored(fullKey, index) {
+    if (index.keys.has(fullKey))
+        return true;
+    for (const ns of index.namespaces) {
+        if (fullKey === ns || fullKey.startsWith(`${ns}.`))
+            return true;
+    }
+    return false;
+}
+/** Glob-lite for `strict.unusedIgnore` (`common.*`, `*.seeAll`). */
+export function matchesUnusedIgnoreGlob(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;
+}

package/dist/compiler/validate/usage.js

@@ -1,5 +1,7 @@
-import { loadLocaleMessages } from '../load-messages.js';
+import { readFile } from 'node:fs/promises';
+import { loadLocaleMessages, resolveMessagePath, } from '../load-messages.js';
 import { DEFAULT_SCAN_ROOTS, scanKeys } from '../scan-keys.js';
+import { collectUnusedIgnores, isUnusedIgnored, matchesUnusedIgnoreGlob, } from '../unused-meta.js';
 function severityFor(level, alwaysError = false) {
     if (alwaysError)
         return 'error';
@@ -11,25 +13,6 @@ function namespaceOf(fullKey) {
     const i = fullKey.indexOf('.');
     return i === -1 ? '_root' : fullKey.slice(0, i);
 }
-/** 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 = [];
@@ -71,10 +54,13 @@ export async function validateUsage(config, cwd) {
     const unusedSev = severityFor(config.strict.unused);
     if (unusedSev) {
         const ignore = config.strict.unusedIgnore;
+        const metaIgnores = await loadUnusedMetaIgnores(config, cwd);
         for (const fullKey of defined) {
             if (used.has(fullKey))
                 continue;
-            if (matchesIgnore(fullKey, ignore))
+            if (matchesUnusedIgnoreGlob(fullKey, ignore))
+                continue;
+            if (isUnusedIgnored(fullKey, metaIgnores))
                 continue;
             // Dynamic t(var) / t.ns / t.dynamic — do not false-flag catalog keys as unused
             if (dynamicNamespaces.has(namespaceOf(fullKey)))
@@ -90,3 +76,14 @@ export async function validateUsage(config, cwd) {
     }
     return issues;
 }
+async function loadUnusedMetaIgnores(config, cwd) {
+    const abs = resolveMessagePath(cwd, config.messages, config.defaultLocale);
+    try {
+        const raw = await readFile(abs, 'utf8');
+        const json = JSON.parse(raw);
+        return collectUnusedIgnores(json);
+    }
+    catch {
+        return collectUnusedIgnores({});
+    }
+}

package/package.json

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