@noctcore/eslint-plugin-contracts 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,81 @@
 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';
+}
+
+interface FetchMustCheckOkOptions {
+    /**
+     * Callees whose result is a `Response`: a bare name (`fetch`) or a dotted path
+     * (`globalThis.fetch`, `http.fetchWithRetry`). Default `['fetch']`.
+     */
+    readonly fetchFunctions?: readonly string[];
+}
+
+interface SchemaEnumFieldConsistencyOptions {
+    /** Names the zod namespace is imported under. */
+    readonly zodIdentifiers?: readonly string[];
+    /** Field names allowed to be an enum in one schema and a string in another. */
+    readonly ignoreFields?: readonly string[];
+    /**
+     * Regex source. An IMPORTED identifier counts as an enum only when its name
+     * matches. Unset, no imported identifier does.
+     */
+    readonly enumIdentifierPattern?: string;
+}
+
 interface EnvVarSchemaParityOptions {
     /** Path to the env declaration source — a `.env.example` or a zod-env module. Empty = rule is inert. */
     readonly schema?: string;
@@ -83,6 +159,15 @@ declare const rules: {
     'require-schema-parse-at-boundary': _typescript_eslint_utils_ts_eslint.RuleModule<"castedBoundaryData", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    'schema-enum-field-consistency': _typescript_eslint_utils_ts_eslint.RuleModule<"widenedEnumField", [SchemaEnumFieldConsistencyOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'fetch-must-check-ok': _typescript_eslint_utils_ts_eslint.RuleModule<"missingOkCheck", [FetchMustCheckOkOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'translation-key-exists': _typescript_eslint_utils_ts_eslint.RuleModule<"missingKey" | "missingKeyPrefix" | "unknownNamespace" | "catalogUnreadable", [TranslationKeyExistsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 
 declare const plugin: {
@@ -121,6 +206,15 @@ declare const plugin: {
         'require-schema-parse-at-boundary': _typescript_eslint_utils_ts_eslint.RuleModule<"castedBoundaryData", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        'schema-enum-field-consistency': _typescript_eslint_utils_ts_eslint.RuleModule<"widenedEnumField", [SchemaEnumFieldConsistencyOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'fetch-must-check-ok': _typescript_eslint_utils_ts_eslint.RuleModule<"missingOkCheck", [FetchMustCheckOkOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'translation-key-exists': _typescript_eslint_utils_ts_eslint.RuleModule<"missingKey" | "missingKeyPrefix" | "unknownNamespace" | "catalogUnreadable", [TranslationKeyExistsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
     configs: Record<string, unknown>;
 };

package/dist/index.d.ts

@@ -1,5 +1,81 @@
 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';
+}
+
+interface FetchMustCheckOkOptions {
+    /**
+     * Callees whose result is a `Response`: a bare name (`fetch`) or a dotted path
+     * (`globalThis.fetch`, `http.fetchWithRetry`). Default `['fetch']`.
+     */
+    readonly fetchFunctions?: readonly string[];
+}
+
+interface SchemaEnumFieldConsistencyOptions {
+    /** Names the zod namespace is imported under. */
+    readonly zodIdentifiers?: readonly string[];
+    /** Field names allowed to be an enum in one schema and a string in another. */
+    readonly ignoreFields?: readonly string[];
+    /**
+     * Regex source. An IMPORTED identifier counts as an enum only when its name
+     * matches. Unset, no imported identifier does.
+     */
+    readonly enumIdentifierPattern?: string;
+}
+
 interface EnvVarSchemaParityOptions {
     /** Path to the env declaration source — a `.env.example` or a zod-env module. Empty = rule is inert. */
     readonly schema?: string;
@@ -83,6 +159,15 @@ declare const rules: {
     'require-schema-parse-at-boundary': _typescript_eslint_utils_ts_eslint.RuleModule<"castedBoundaryData", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    'schema-enum-field-consistency': _typescript_eslint_utils_ts_eslint.RuleModule<"widenedEnumField", [SchemaEnumFieldConsistencyOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'fetch-must-check-ok': _typescript_eslint_utils_ts_eslint.RuleModule<"missingOkCheck", [FetchMustCheckOkOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
+    'translation-key-exists': _typescript_eslint_utils_ts_eslint.RuleModule<"missingKey" | "missingKeyPrefix" | "unknownNamespace" | "catalogUnreadable", [TranslationKeyExistsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
 };
 
 declare const plugin: {
@@ -121,6 +206,15 @@ declare const plugin: {
         'require-schema-parse-at-boundary': _typescript_eslint_utils_ts_eslint.RuleModule<"castedBoundaryData", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        'schema-enum-field-consistency': _typescript_eslint_utils_ts_eslint.RuleModule<"widenedEnumField", [SchemaEnumFieldConsistencyOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'fetch-must-check-ok': _typescript_eslint_utils_ts_eslint.RuleModule<"missingOkCheck", [FetchMustCheckOkOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
+        'translation-key-exists': _typescript_eslint_utils_ts_eslint.RuleModule<"missingKey" | "missingKeyPrefix" | "unknownNamespace" | "catalogUnreadable", [TranslationKeyExistsOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
     };
     configs: Record<string, unknown>;
 };