@noctcore/eslint-plugin-contracts 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -30,9 +30,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  TRANSLATION_DEFAULTS: () => TRANSLATION_DEFAULTS,
+  catalogHasKey: () => catalogHasKey,
+  catalogHasPrefix: () => catalogHasPrefix,
+  catalogsForNamespace: () => catalogsForNamespace,
   configs: () => configs,
+  createTranslationVisitor: () => createTranslationVisitor,
   default: () => index_default,
-  rules: () => rules
+  rules: () => rules,
+  translationSettingsOf: () => translationSettingsOf
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -2302,6 +2308,12 @@ var configs = plugin.configs;
 var index_default = plugin;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  TRANSLATION_DEFAULTS,
+  catalogHasKey,
+  catalogHasPrefix,
+  catalogsForNamespace,
   configs,
-  rules
+  createTranslationVisitor,
+  rules,
+  translationSettingsOf
 });

package/dist/index.d.cts

@@ -1,60 +1,5 @@
 import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
-
-/**
- * Translation catalog loading for the i18n rules.
- *
- * A catalog is a JSON file (or a subtree of one) that holds the keys of ONE
- * namespace. Projects lay catalogs out in a handful of shapes, and a
- * `CatalogSource` describes each of them without the rule knowing any project:
- *
- *   one file per namespace   `{ file: 'locales/en/{ns}.json' }`
- *   one file, ns at the top  `{ file: 'locales/en.json', keyPath: '{ns}' }`
- *   a fixed file for one ns  `{ file: 'src/i18n/en.json', namespace: 'common' }`
- *   single-namespace app     `{ file: 'src/i18n/en.json' }` (the default namespace)
- *
- * `{ns}` is substituted with the namespace being resolved. A templated source
- * whose file or subtree does not exist simply does not supply that namespace;
- * a FIXED source that cannot be read is a configuration error and is surfaced.
- */
-interface CatalogSource {
-    /** JSON catalog path, relative to the ESLint cwd. May contain `{ns}`. */
-    readonly file: string;
-    /** Namespace a fixed (non-templated) source supplies. Defaults to the default namespace. */
-    readonly namespace?: string;
-    /** Dot-separated subtree inside the file holding the namespace's keys. May contain `{ns}`. */
-    readonly keyPath?: string;
-}
-
-interface TranslationKeyExistsOptions {
-    /** Where each namespace's catalog lives. Empty = rule is inert. */
-    readonly catalogs?: readonly CatalogSource[];
-    /** The namespace an unqualified `useTranslation()` / `i18n.t` resolves to (i18next `defaultNS`). */
-    readonly defaultNamespace?: string;
-    /** Namespaces searched after the bound ones (i18next `fallbackNS`). */
-    readonly fallbackNamespaces?: readonly string[];
-    /** Hooks returning a namespace-bound `t` (`useTranslation`). */
-    readonly hooks?: readonly string[];
-    /** i18next instance identifiers: `<instance>.t(...)`, `<instance>.getFixedT(...)`. */
-    readonly instances?: readonly string[];
-    /** Free translation functions bound to the default namespace when imported or global (`t`). */
-    readonly functions?: readonly string[];
-    /** Type names whose first type argument names a parameter's namespace (`TFunction<'ns'>`). */
-    readonly typeNames?: readonly string[];
-    /** JSX components taking an `i18nKey` prop (`Trans`). */
-    readonly transComponents?: readonly string[];
-    /** Identifiers holding a namespace name that live in another module (`{ HELP_NS: 'help' }`). */
-    readonly namespaceIdentifiers?: Readonly<Record<string, string>>;
-    /** i18next `nsSeparator`; `false` disables `ns:key` parsing. */
-    readonly nsSeparator?: string | false;
-    /** i18next `keySeparator`; `false` means flat catalogs. */
-    readonly keySeparator?: string | false;
-    /** i18next `pluralSeparator`. */
-    readonly pluralSeparator?: string;
-    /** i18next `contextSeparator`. */
-    readonly contextSeparator?: string;
-    /** `ignore` stays silent on template keys; `check-prefix` requires their static head to exist. */
-    readonly dynamicKeys?: 'ignore' | 'check-prefix';
-}
+import { TSESTree, TSESLint } from '@typescript-eslint/utils';
 
 interface FetchMustCheckOkOptions {
     /**
@@ -127,6 +72,173 @@ interface ZodSchemaNamingOptions {
     readonly roleSuffixes?: readonly string[];
 }
 
+/**
+ * Translation catalog loading for the i18n rules.
+ *
+ * A catalog is a JSON file (or a subtree of one) that holds the keys of ONE
+ * namespace. Projects lay catalogs out in a handful of shapes, and a
+ * `CatalogSource` describes each of them without the rule knowing any project:
+ *
+ *   one file per namespace   `{ file: 'locales/en/{ns}.json' }`
+ *   one file, ns at the top  `{ file: 'locales/en.json', keyPath: '{ns}' }`
+ *   a fixed file for one ns  `{ file: 'src/i18n/en.json', namespace: 'common' }`
+ *   single-namespace app     `{ file: 'src/i18n/en.json' }` (the default namespace)
+ *
+ * `{ns}` is substituted with the namespace being resolved. A templated source
+ * whose file or subtree does not exist simply does not supply that namespace;
+ * a FIXED source that cannot be read is a configuration error and is surfaced.
+ */
+interface CatalogSource {
+    /** JSON catalog path, relative to the ESLint cwd. May contain `{ns}`. */
+    readonly file: string;
+    /** Namespace a fixed (non-templated) source supplies. Defaults to the default namespace. */
+    readonly namespace?: string;
+    /** Dot-separated subtree inside the file holding the namespace's keys. May contain `{ns}`. */
+    readonly keyPath?: string;
+}
+/** The flattened key space of one namespace catalog. */
+interface Catalog {
+    /** Where the keys came from, for messages: `file` or `file#keyPath`. */
+    readonly label: string;
+    /** Every leaf key (a string / number / boolean value), joined by the key separator. */
+    readonly leaves: ReadonlySet<string>;
+    /** Every non-leaf key (an object or array), joined by the key separator. */
+    readonly branches: ReadonlySet<string>;
+}
+/** Outcome of resolving one namespace against every configured source. */
+interface NamespaceCatalogs {
+    readonly catalogs: readonly Catalog[];
+    /** Fixed sources that should supply this namespace but could not be loaded. */
+    readonly errors: readonly string[];
+}
+/** Every catalog the configured sources supply for `namespace`, in source order. */
+declare function catalogsForNamespace(namespace: string, sources: readonly CatalogSource[], settings: {
+    readonly cwd: string;
+    readonly defaultNamespace: string;
+    readonly keySeparator: string | false;
+}): NamespaceCatalogs;
+interface KeyLookup {
+    /** Plural forms may answer for the key (the call passes, or may pass, `count`). */
+    readonly plural: boolean;
+    /** Context variants may answer for the key (the call passes, or may pass, `context`). */
+    readonly context: boolean;
+    /** The call asks for an object (`returnObjects`), so a branch answers too. */
+    readonly returnObjects: boolean;
+    readonly pluralSeparator: string;
+    readonly contextSeparator: string;
+}
+/** Does `key` resolve in `catalog` the way i18next would look it up? */
+declare function catalogHasKey(catalog: Catalog, key: string, lookup: KeyLookup): boolean;
+/** Does any key in `catalog` start with `prefix`? (the `dynamicKeys: 'check-prefix'` probe) */
+declare function catalogHasPrefix(catalog: Catalog, prefix: string): boolean;
+
+/**
+ * Static discovery of translation-key usages, i18next / react-i18next style.
+ *
+ * The visitor answers one question per call site: "which key, in which
+ * namespace(s)?" It never guesses. Every shape it cannot pin down statically
+ * (a variable key, a namespace held in a variable it cannot resolve, an opaque
+ * options bag) comes back as `dynamic` / `unresolved` so the caller can stay
+ * silent on it, the way sibling rules stay silent on spreads.
+ *
+ * Namespace sources it understands, all by syntax, all per file:
+ *   `const { t } = useTranslation('ns', { keyPrefix })`  (also `[t]`, `r.t`, aliases)
+ *   `const t = i18n.getFixedT(lng, 'ns', keyPrefix)`
+ *   `i18n.t(...)` / `i18next.t(...)`                     (default namespace)
+ *   `function f(t: TFunction<'ns'>)`                      (typed parameter)
+ *   `import { t } from 'i18next'` or a global `t`         (default namespace)
+ *   per call: `t('ns:key')`, `t('key', { ns: 'ns' })`
+ *   JSX: `<Trans i18nKey="key" ns="ns" t={t} />`
+ * A namespace argument may be a literal, an array of literals, a same-file
+ * `const`, a name mapped in `namespaceIdentifiers`, or (under typed linting)
+ * any identifier whose type is a single string literal.
+ */
+interface TranslationSettings {
+    readonly hooks: ReadonlySet<string>;
+    readonly instances: ReadonlySet<string>;
+    readonly functions: ReadonlySet<string>;
+    readonly typeNames: ReadonlySet<string>;
+    readonly transComponents: ReadonlySet<string>;
+    readonly namespaceIdentifiers: Readonly<Record<string, string>>;
+    readonly defaultNamespace: string;
+    readonly nsSeparator: string | false;
+    readonly keySeparator: string | false;
+}
+type TranslationUsage = {
+    /** Every key is static: the call is checkable. */
+    readonly kind: 'key';
+    readonly node: TSESTree.Node;
+    /** Namespaces i18next would search, in order. */
+    readonly namespaces: readonly string[];
+    /** Candidate keys (more than one for `t(['a', 'b'])`); any one resolving is enough. */
+    readonly keys: readonly string[];
+    readonly plural: boolean;
+    readonly context: boolean;
+    readonly returnObjects: boolean;
+} | {
+    /** A template key with a static head: only its prefix is known. */
+    readonly kind: 'prefix';
+    readonly node: TSESTree.Node;
+    readonly namespaces: readonly string[];
+    readonly prefix: string;
+} | {
+    /** The key itself is not static (`t(someVariable)`, `` t(`${x}`) ``). */
+    readonly kind: 'dynamic';
+    readonly node: TSESTree.Node;
+} | {
+    /** A translation call whose namespace or options cannot be resolved statically. */
+    readonly kind: 'unresolved';
+    readonly node: TSESTree.Node;
+};
+type Context = Readonly<TSESLint.RuleContext<string, readonly unknown[]>>;
+declare function createTranslationVisitor(context: Context, settings: TranslationSettings, onUsage: (usage: TranslationUsage) => void): TSESLint.RuleListener;
+
+interface TranslationKeyExistsOptions {
+    /** Where each namespace's catalog lives. Empty = rule is inert. */
+    readonly catalogs?: readonly CatalogSource[];
+    /** The namespace an unqualified `useTranslation()` / `i18n.t` resolves to (i18next `defaultNS`). */
+    readonly defaultNamespace?: string;
+    /** Namespaces searched after the bound ones (i18next `fallbackNS`). */
+    readonly fallbackNamespaces?: readonly string[];
+    /** Hooks returning a namespace-bound `t` (`useTranslation`). */
+    readonly hooks?: readonly string[];
+    /** i18next instance identifiers: `<instance>.t(...)`, `<instance>.getFixedT(...)`. */
+    readonly instances?: readonly string[];
+    /** Free translation functions bound to the default namespace when imported or global (`t`). */
+    readonly functions?: readonly string[];
+    /** Type names whose first type argument names a parameter's namespace (`TFunction<'ns'>`). */
+    readonly typeNames?: readonly string[];
+    /** JSX components taking an `i18nKey` prop (`Trans`). */
+    readonly transComponents?: readonly string[];
+    /** Identifiers holding a namespace name that live in another module (`{ HELP_NS: 'help' }`). */
+    readonly namespaceIdentifiers?: Readonly<Record<string, string>>;
+    /** i18next `nsSeparator`; `false` disables `ns:key` parsing. */
+    readonly nsSeparator?: string | false;
+    /** i18next `keySeparator`; `false` means flat catalogs. */
+    readonly keySeparator?: string | false;
+    /** i18next `pluralSeparator`. */
+    readonly pluralSeparator?: string;
+    /** i18next `contextSeparator`. */
+    readonly contextSeparator?: string;
+    /** `ignore` stays silent on template keys; `check-prefix` requires their static head to exist. */
+    readonly dynamicKeys?: 'ignore' | 'check-prefix';
+}
+/** Defaults mirror i18next / react-i18next's own. */
+declare const TRANSLATION_DEFAULTS: {
+    readonly defaultNamespace: "translation";
+    readonly hooks: readonly ["useTranslation"];
+    readonly instances: readonly ["i18n", "i18next"];
+    readonly functions: readonly ["t"];
+    readonly typeNames: readonly ["TFunction"];
+    readonly transComponents: readonly ["Trans"];
+    readonly nsSeparator: ":";
+    readonly keySeparator: ".";
+    readonly pluralSeparator: "_";
+    readonly contextSeparator: "_";
+};
+/** Normalise user options into the visitor's settings. */
+declare function translationSettingsOf(options: TranslationKeyExistsOptions): TranslationSettings;
+
 /** Every rule this plugin exposes, keyed by its (unprefixed) rule id. */
 declare const rules: {
     'zod-schema-naming': _typescript_eslint_utils_ts_eslint.RuleModule<"schemaNaming" | "missingType", [ZodSchemaNamingOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -221,4 +333,4 @@ declare const plugin: {
 
 declare const configs: Record<string, unknown>;
 
-export { configs, plugin as default, rules };
+export { type Catalog, type CatalogSource, type KeyLookup, type NamespaceCatalogs, TRANSLATION_DEFAULTS, type TranslationKeyExistsOptions, type TranslationSettings, type TranslationUsage, catalogHasKey, catalogHasPrefix, catalogsForNamespace, configs, createTranslationVisitor, plugin as default, rules, translationSettingsOf };

package/dist/index.d.ts

@@ -1,60 +1,5 @@
 import * as _typescript_eslint_utils_ts_eslint from '@typescript-eslint/utils/ts-eslint';
-
-/**
- * Translation catalog loading for the i18n rules.
- *
- * A catalog is a JSON file (or a subtree of one) that holds the keys of ONE
- * namespace. Projects lay catalogs out in a handful of shapes, and a
- * `CatalogSource` describes each of them without the rule knowing any project:
- *
- *   one file per namespace   `{ file: 'locales/en/{ns}.json' }`
- *   one file, ns at the top  `{ file: 'locales/en.json', keyPath: '{ns}' }`
- *   a fixed file for one ns  `{ file: 'src/i18n/en.json', namespace: 'common' }`
- *   single-namespace app     `{ file: 'src/i18n/en.json' }` (the default namespace)
- *
- * `{ns}` is substituted with the namespace being resolved. A templated source
- * whose file or subtree does not exist simply does not supply that namespace;
- * a FIXED source that cannot be read is a configuration error and is surfaced.
- */
-interface CatalogSource {
-    /** JSON catalog path, relative to the ESLint cwd. May contain `{ns}`. */
-    readonly file: string;
-    /** Namespace a fixed (non-templated) source supplies. Defaults to the default namespace. */
-    readonly namespace?: string;
-    /** Dot-separated subtree inside the file holding the namespace's keys. May contain `{ns}`. */
-    readonly keyPath?: string;
-}
-
-interface TranslationKeyExistsOptions {
-    /** Where each namespace's catalog lives. Empty = rule is inert. */
-    readonly catalogs?: readonly CatalogSource[];
-    /** The namespace an unqualified `useTranslation()` / `i18n.t` resolves to (i18next `defaultNS`). */
-    readonly defaultNamespace?: string;
-    /** Namespaces searched after the bound ones (i18next `fallbackNS`). */
-    readonly fallbackNamespaces?: readonly string[];
-    /** Hooks returning a namespace-bound `t` (`useTranslation`). */
-    readonly hooks?: readonly string[];
-    /** i18next instance identifiers: `<instance>.t(...)`, `<instance>.getFixedT(...)`. */
-    readonly instances?: readonly string[];
-    /** Free translation functions bound to the default namespace when imported or global (`t`). */
-    readonly functions?: readonly string[];
-    /** Type names whose first type argument names a parameter's namespace (`TFunction<'ns'>`). */
-    readonly typeNames?: readonly string[];
-    /** JSX components taking an `i18nKey` prop (`Trans`). */
-    readonly transComponents?: readonly string[];
-    /** Identifiers holding a namespace name that live in another module (`{ HELP_NS: 'help' }`). */
-    readonly namespaceIdentifiers?: Readonly<Record<string, string>>;
-    /** i18next `nsSeparator`; `false` disables `ns:key` parsing. */
-    readonly nsSeparator?: string | false;
-    /** i18next `keySeparator`; `false` means flat catalogs. */
-    readonly keySeparator?: string | false;
-    /** i18next `pluralSeparator`. */
-    readonly pluralSeparator?: string;
-    /** i18next `contextSeparator`. */
-    readonly contextSeparator?: string;
-    /** `ignore` stays silent on template keys; `check-prefix` requires their static head to exist. */
-    readonly dynamicKeys?: 'ignore' | 'check-prefix';
-}
+import { TSESTree, TSESLint } from '@typescript-eslint/utils';
 
 interface FetchMustCheckOkOptions {
     /**
@@ -127,6 +72,173 @@ interface ZodSchemaNamingOptions {
     readonly roleSuffixes?: readonly string[];
 }
 
+/**
+ * Translation catalog loading for the i18n rules.
+ *
+ * A catalog is a JSON file (or a subtree of one) that holds the keys of ONE
+ * namespace. Projects lay catalogs out in a handful of shapes, and a
+ * `CatalogSource` describes each of them without the rule knowing any project:
+ *
+ *   one file per namespace   `{ file: 'locales/en/{ns}.json' }`
+ *   one file, ns at the top  `{ file: 'locales/en.json', keyPath: '{ns}' }`
+ *   a fixed file for one ns  `{ file: 'src/i18n/en.json', namespace: 'common' }`
+ *   single-namespace app     `{ file: 'src/i18n/en.json' }` (the default namespace)
+ *
+ * `{ns}` is substituted with the namespace being resolved. A templated source
+ * whose file or subtree does not exist simply does not supply that namespace;
+ * a FIXED source that cannot be read is a configuration error and is surfaced.
+ */
+interface CatalogSource {
+    /** JSON catalog path, relative to the ESLint cwd. May contain `{ns}`. */
+    readonly file: string;
+    /** Namespace a fixed (non-templated) source supplies. Defaults to the default namespace. */
+    readonly namespace?: string;
+    /** Dot-separated subtree inside the file holding the namespace's keys. May contain `{ns}`. */
+    readonly keyPath?: string;
+}
+/** The flattened key space of one namespace catalog. */
+interface Catalog {
+    /** Where the keys came from, for messages: `file` or `file#keyPath`. */
+    readonly label: string;
+    /** Every leaf key (a string / number / boolean value), joined by the key separator. */
+    readonly leaves: ReadonlySet<string>;
+    /** Every non-leaf key (an object or array), joined by the key separator. */
+    readonly branches: ReadonlySet<string>;
+}
+/** Outcome of resolving one namespace against every configured source. */
+interface NamespaceCatalogs {
+    readonly catalogs: readonly Catalog[];
+    /** Fixed sources that should supply this namespace but could not be loaded. */
+    readonly errors: readonly string[];
+}
+/** Every catalog the configured sources supply for `namespace`, in source order. */
+declare function catalogsForNamespace(namespace: string, sources: readonly CatalogSource[], settings: {
+    readonly cwd: string;
+    readonly defaultNamespace: string;
+    readonly keySeparator: string | false;
+}): NamespaceCatalogs;
+interface KeyLookup {
+    /** Plural forms may answer for the key (the call passes, or may pass, `count`). */
+    readonly plural: boolean;
+    /** Context variants may answer for the key (the call passes, or may pass, `context`). */
+    readonly context: boolean;
+    /** The call asks for an object (`returnObjects`), so a branch answers too. */
+    readonly returnObjects: boolean;
+    readonly pluralSeparator: string;
+    readonly contextSeparator: string;
+}
+/** Does `key` resolve in `catalog` the way i18next would look it up? */
+declare function catalogHasKey(catalog: Catalog, key: string, lookup: KeyLookup): boolean;
+/** Does any key in `catalog` start with `prefix`? (the `dynamicKeys: 'check-prefix'` probe) */
+declare function catalogHasPrefix(catalog: Catalog, prefix: string): boolean;
+
+/**
+ * Static discovery of translation-key usages, i18next / react-i18next style.
+ *
+ * The visitor answers one question per call site: "which key, in which
+ * namespace(s)?" It never guesses. Every shape it cannot pin down statically
+ * (a variable key, a namespace held in a variable it cannot resolve, an opaque
+ * options bag) comes back as `dynamic` / `unresolved` so the caller can stay
+ * silent on it, the way sibling rules stay silent on spreads.
+ *
+ * Namespace sources it understands, all by syntax, all per file:
+ *   `const { t } = useTranslation('ns', { keyPrefix })`  (also `[t]`, `r.t`, aliases)
+ *   `const t = i18n.getFixedT(lng, 'ns', keyPrefix)`
+ *   `i18n.t(...)` / `i18next.t(...)`                     (default namespace)
+ *   `function f(t: TFunction<'ns'>)`                      (typed parameter)
+ *   `import { t } from 'i18next'` or a global `t`         (default namespace)
+ *   per call: `t('ns:key')`, `t('key', { ns: 'ns' })`
+ *   JSX: `<Trans i18nKey="key" ns="ns" t={t} />`
+ * A namespace argument may be a literal, an array of literals, a same-file
+ * `const`, a name mapped in `namespaceIdentifiers`, or (under typed linting)
+ * any identifier whose type is a single string literal.
+ */
+interface TranslationSettings {
+    readonly hooks: ReadonlySet<string>;
+    readonly instances: ReadonlySet<string>;
+    readonly functions: ReadonlySet<string>;
+    readonly typeNames: ReadonlySet<string>;
+    readonly transComponents: ReadonlySet<string>;
+    readonly namespaceIdentifiers: Readonly<Record<string, string>>;
+    readonly defaultNamespace: string;
+    readonly nsSeparator: string | false;
+    readonly keySeparator: string | false;
+}
+type TranslationUsage = {
+    /** Every key is static: the call is checkable. */
+    readonly kind: 'key';
+    readonly node: TSESTree.Node;
+    /** Namespaces i18next would search, in order. */
+    readonly namespaces: readonly string[];
+    /** Candidate keys (more than one for `t(['a', 'b'])`); any one resolving is enough. */
+    readonly keys: readonly string[];
+    readonly plural: boolean;
+    readonly context: boolean;
+    readonly returnObjects: boolean;
+} | {
+    /** A template key with a static head: only its prefix is known. */
+    readonly kind: 'prefix';
+    readonly node: TSESTree.Node;
+    readonly namespaces: readonly string[];
+    readonly prefix: string;
+} | {
+    /** The key itself is not static (`t(someVariable)`, `` t(`${x}`) ``). */
+    readonly kind: 'dynamic';
+    readonly node: TSESTree.Node;
+} | {
+    /** A translation call whose namespace or options cannot be resolved statically. */
+    readonly kind: 'unresolved';
+    readonly node: TSESTree.Node;
+};
+type Context = Readonly<TSESLint.RuleContext<string, readonly unknown[]>>;
+declare function createTranslationVisitor(context: Context, settings: TranslationSettings, onUsage: (usage: TranslationUsage) => void): TSESLint.RuleListener;
+
+interface TranslationKeyExistsOptions {
+    /** Where each namespace's catalog lives. Empty = rule is inert. */
+    readonly catalogs?: readonly CatalogSource[];
+    /** The namespace an unqualified `useTranslation()` / `i18n.t` resolves to (i18next `defaultNS`). */
+    readonly defaultNamespace?: string;
+    /** Namespaces searched after the bound ones (i18next `fallbackNS`). */
+    readonly fallbackNamespaces?: readonly string[];
+    /** Hooks returning a namespace-bound `t` (`useTranslation`). */
+    readonly hooks?: readonly string[];
+    /** i18next instance identifiers: `<instance>.t(...)`, `<instance>.getFixedT(...)`. */
+    readonly instances?: readonly string[];
+    /** Free translation functions bound to the default namespace when imported or global (`t`). */
+    readonly functions?: readonly string[];
+    /** Type names whose first type argument names a parameter's namespace (`TFunction<'ns'>`). */
+    readonly typeNames?: readonly string[];
+    /** JSX components taking an `i18nKey` prop (`Trans`). */
+    readonly transComponents?: readonly string[];
+    /** Identifiers holding a namespace name that live in another module (`{ HELP_NS: 'help' }`). */
+    readonly namespaceIdentifiers?: Readonly<Record<string, string>>;
+    /** i18next `nsSeparator`; `false` disables `ns:key` parsing. */
+    readonly nsSeparator?: string | false;
+    /** i18next `keySeparator`; `false` means flat catalogs. */
+    readonly keySeparator?: string | false;
+    /** i18next `pluralSeparator`. */
+    readonly pluralSeparator?: string;
+    /** i18next `contextSeparator`. */
+    readonly contextSeparator?: string;
+    /** `ignore` stays silent on template keys; `check-prefix` requires their static head to exist. */
+    readonly dynamicKeys?: 'ignore' | 'check-prefix';
+}
+/** Defaults mirror i18next / react-i18next's own. */
+declare const TRANSLATION_DEFAULTS: {
+    readonly defaultNamespace: "translation";
+    readonly hooks: readonly ["useTranslation"];
+    readonly instances: readonly ["i18n", "i18next"];
+    readonly functions: readonly ["t"];
+    readonly typeNames: readonly ["TFunction"];
+    readonly transComponents: readonly ["Trans"];
+    readonly nsSeparator: ":";
+    readonly keySeparator: ".";
+    readonly pluralSeparator: "_";
+    readonly contextSeparator: "_";
+};
+/** Normalise user options into the visitor's settings. */
+declare function translationSettingsOf(options: TranslationKeyExistsOptions): TranslationSettings;
+
 /** Every rule this plugin exposes, keyed by its (unprefixed) rule id. */
 declare const rules: {
     'zod-schema-naming': _typescript_eslint_utils_ts_eslint.RuleModule<"schemaNaming" | "missingType", [ZodSchemaNamingOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
@@ -221,4 +333,4 @@ declare const plugin: {
 
 declare const configs: Record<string, unknown>;
 
-export { configs, plugin as default, rules };
+export { type Catalog, type CatalogSource, type KeyLookup, type NamespaceCatalogs, TRANSLATION_DEFAULTS, type TranslationKeyExistsOptions, type TranslationSettings, type TranslationUsage, catalogHasKey, catalogHasPrefix, catalogsForNamespace, configs, createTranslationVisitor, plugin as default, rules, translationSettingsOf };

package/dist/index.js

@@ -2263,7 +2263,13 @@ plugin.configs.recommended = {
 var configs = plugin.configs;
 var index_default = plugin;
 export {
+  TRANSLATION_DEFAULTS,
+  catalogHasKey,
+  catalogHasPrefix,
+  catalogsForNamespace,
   configs,
+  createTranslationVisitor,
   index_default as default,
-  rules
+  rules,
+  translationSettingsOf
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-contracts",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "ESLint rules for shared contract, config, error-handling, and money-precision conventions (zod schema naming, wire discriminants, no-direct-process-env, decimal money).",
   "license": "MIT",
   "type": "module",