@od-oneapp/config 2026.2.2001-canary.1

package/eslint/__tests__/config-structure.test.mjs

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview config-structure.test.mjs
+ */
+
+import { describe, expect, it } from 'vitest';
+
+
+// Import all exported configs
+import expoConfig from '../expo.mjs';
+import nextConfig from '../next.mjs';
+import nodeConfig from '../node.mjs';
+import reactConfig from '../react.mjs';
+import storybookConfig from '../storybook.mjs';
+import testConfig from '../test.mjs';
+import { validateESLintConfig } from '../utils/validate-config.mjs';
+
+describe('ESLint Config Structure Validation', () => {
+  it('should validate node config structure', () => {
+    expect(validateESLintConfig(nodeConfig, 'node')).toBe(true);
+  });
+
+  it('should validate react config structure', () => {
+    expect(validateESLintConfig(reactConfig, 'react')).toBe(true);
+  });
+
+  it('should validate next config structure', () => {
+    expect(validateESLintConfig(nextConfig, 'next')).toBe(true);
+  });
+
+  it('should validate expo config structure', () => {
+    expect(validateESLintConfig(expoConfig, 'expo')).toBe(true);
+  });
+
+  it('should validate storybook config structure', () => {
+    expect(validateESLintConfig(storybookConfig, 'storybook')).toBe(true);
+  });
+
+  it('should validate test config structure', () => {
+    expect(validateESLintConfig(testConfig, 'test')).toBe(true);
+  });
+});
+
+describe('ESLint Config Structure Validation - Invalid Cases', () => {
+  it('should throw on null config', () => {
+    expect(() => validateESLintConfig(null, 'null-test')).toThrow(
+      '[null-test] Config must be an object or array',
+    );
+  });
+
+  it('should throw on primitive config', () => {
+    expect(() => validateESLintConfig('string', 'string-test')).toThrow(
+      '[string-test] Config must be an object or array',
+    );
+  });
+
+  it('should throw on config with invalid plugins type', () => {
+    expect(() => validateESLintConfig({ plugins: 'invalid' }, 'invalid-plugins')).toThrow(
+      '[invalid-plugins] plugins must be an object',
+    );
+  });
+});

package/eslint/base.mjs

@@ -0,0 +1,350 @@
+/**
+ * @fileoverview Base ESLint configuration for the monorepo
+ *
+ * This is the foundation configuration that all other ESLint configs extend.
+ * It includes:
+ * - TypeScript ESLint recommended rules
+ * - Security rules (OWASP)
+ * - Promise best practices
+ * - Unused imports detection
+ * - JSDoc validation
+ * - YAML and JSON validation
+ * - Custom rules (no-used-underscore-vars)
+ *
+ * **Note**: This config is internal-only and not exported. Use specific configs
+ * like `@od-oneapp/config/eslint/node`, `@od-oneapp/config/eslint/react`, etc.
+ */
+
+import prettier from 'eslint-config-prettier';
+import jsdoc from 'eslint-plugin-jsdoc';
+import pnpmPlugin from 'eslint-plugin-pnpm';
+import promisePlugin from 'eslint-plugin-promise';
+import securityPlugin from 'eslint-plugin-security';
+import unusedImportsPlugin from 'eslint-plugin-unused-imports';
+import ymlPlugin from 'eslint-plugin-yml';
+import jsoncParser from 'jsonc-eslint-parser';
+import tseslint from 'typescript-eslint';
+import * as yamlParser from 'yaml-eslint-parser';
+
+import noUsedUnderscoreVars from './rules/no-used-underscore-vars.mjs';
+import { GLOBAL_IGNORES, TYPE_AWARE_IGNORES } from './shared/common-ignores.mjs';
+import { DISABLED_TYPE_AWARE_RULES } from './shared/disabled-type-aware-rules.mjs';
+import { createValidatedConfig } from './utils/create-validated-config.mjs';
+
+/**
+ * Base ESLint configuration array
+ *
+ * @type {import('typescript-eslint').ConfigArray}
+ */
+const config = tseslint.config(
+  {
+    // Global ignores - applies to all files
+    // Note: .storybook/** is not ignored here so it can be linted by the Storybook config
+    // See shared/common-ignores.mjs for the full list (single source of truth)
+    ignores: GLOBAL_IGNORES,
+  },
+  {
+    files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts', '**/*.js', '**/*.jsx', '**/*.mjs'],
+  },
+  ...tseslint.configs.recommended,
+  prettier,
+  {
+    // Only apply type-aware linting to TypeScript files
+    files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+      },
+    },
+    // Ignore config files and Storybook files - they're handled by specific configs
+    // See shared/common-ignores.mjs TYPE_AWARE_IGNORES for the full list
+    ignores: TYPE_AWARE_IGNORES,
+    rules: {
+      // Disabled in favor of unused-imports plugin
+      '@typescript-eslint/no-unused-vars': 'off',
+      '@typescript-eslint/consistent-type-imports': [
+        'error',
+        {
+          prefer: 'type-imports',
+          fixStyle: 'inline-type-imports',
+        },
+      ],
+    },
+  },
+  {
+    // Security, Promise, and Unused Imports rules
+    files: ['**/*.{ts,tsx,js,jsx,mts,mjs}'],
+    plugins: {
+      security: securityPlugin,
+      promise: promisePlugin,
+      'unused-imports': unusedImportsPlugin,
+      'no-used-underscore-vars': {
+        rules: {
+          'no-used-underscore-vars': noUsedUnderscoreVars,
+        },
+      },
+    },
+    rules: {
+      // Security rules (OWASP)
+      'security/detect-eval-with-expression': 'error',
+      'security/detect-non-literal-require': 'error',
+      'security/detect-buffer-noassert': 'error',
+      'security/detect-unsafe-regex': 'error',
+      'security/detect-child-process': 'error',
+      'security/detect-non-literal-fs-filename': 'warn',
+      'security/detect-object-injection': 'off', // Too noisy
+      'security/detect-possible-timing-attacks': 'warn',
+
+      // Core security
+      'no-eval': 'error',
+      'no-implied-eval': 'error',
+      'no-new-func': 'error',
+
+      // Promise rules
+      'promise/always-return': 'warn',
+      'promise/catch-or-return': 'warn',
+      'promise/no-callback-in-promise': 'warn',
+      'promise/param-names': [
+        'error',
+        {
+          rejectPattern: '^_?reject$',
+          resolvePattern: '^_?resolve$',
+        },
+      ],
+      'promise/prefer-await-to-then': 'warn',
+
+      // Unused imports (replaces TypeScript built-in)
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': [
+        'warn',
+        {
+          args: 'after-used',
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+
+      // Custom rule
+      'no-used-underscore-vars/no-used-underscore-vars': 'error',
+
+      // General best practices (from XO) - apply to all configs
+      // Enforce using @od-oneapp/observability logger instead of console statements
+      // Use: import { logInfo, logWarn, logError, logDebug } from '@od-oneapp/shared/logs/client/next'
+      'no-console': 'error',
+      'no-implicit-coercion': 'error',
+      'no-negated-condition': 'off', // Too opinionated
+      'no-unused-expressions': [
+        'error',
+        {
+          allowShortCircuit: true,
+          allowTernary: true,
+          allowTaggedTemplates: true,
+        },
+      ],
+      'prefer-arrow-callback': ['warn', { allowNamedFunctions: true }],
+      'prefer-const': 'error',
+      'prefer-template': 'error',
+      'object-shorthand': ['error', 'always'],
+      'prefer-destructuring': [
+        'warn',
+        {
+          array: false,
+          object: true,
+        },
+      ],
+    },
+  },
+  {
+    // TypeScript rules only apply to TypeScript files (not .js/.mjs)
+    // Exclude Storybook files, test config files, and generated files
+    // See shared/common-ignores.mjs TYPE_AWARE_IGNORES for the full list
+    files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
+    ignores: TYPE_AWARE_IGNORES,
+    rules: {
+      // Type-aware rules that require parserOptions.projectService
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-misused-promises': [
+        'error',
+        {
+          checksConditionals: true,
+          checksVoidReturn: true,
+        },
+      ],
+      // TODO: Re-enable prefer-nullish-coalescing rule after fixing existing violations
+      // Temporarily disabled due to many existing violations in codebase
+      '@typescript-eslint/prefer-nullish-coalescing': 'off',
+      '@typescript-eslint/prefer-optional-chain': 'error',
+      // Disabled: Too many false positives with runtime checks that TypeScript can't verify
+      // Re-enable if needed after fixing remaining legitimate cases
+      '@typescript-eslint/no-unnecessary-condition': 'off',
+      '@typescript-eslint/no-unnecessary-type-assertion': 'warn',
+      '@typescript-eslint/prefer-as-const': 'error',
+      '@typescript-eslint/switch-exhaustiveness-check': 'warn',
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+      '@typescript-eslint/prefer-includes': 'error',
+      '@typescript-eslint/prefer-string-starts-ends-with': 'error',
+      '@typescript-eslint/no-explicit-any': 'off',
+      // Allow implicit any (no-unsafe-* rules are off)
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/explicit-function-return-type': 'off', // Too strict, TypeScript infers well
+      '@typescript-eslint/strict-boolean-expressions': 'off', // Too strict for most codebases
+    },
+  },
+  {
+    // Discourage JavaScript files - prefer TypeScript
+    files: ['**/*.js', '**/*.jsx', '**/*.mjs'],
+    ignores: ['**/generated/**', '**/dist/**'],
+    rules: {
+      // Note: JavaScript files are supported but discouraged
+      // Prefer TypeScript (.ts/.tsx) for type safety and better DX
+      // Use .mjs only for ESM JavaScript when TypeScript isn't suitable
+      'no-undef': 'error', // Catch undefined variables in JS files
+      // Use standard ESLint no-unused-vars for JS files (disable unused-imports plugin to avoid conflict)
+      'unused-imports/no-unused-vars': 'off',
+      'no-unused-vars': [
+        'warn',
+        {
+          args: 'after-used', // Consistent with TS config
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+      // Disable TypeScript-specific rules for JavaScript files
+      ...DISABLED_TYPE_AWARE_RULES,
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/consistent-type-imports': 'off',
+    },
+  },
+  {
+    // JSDoc plugin for documentation consistency
+    // Note: Most jsdoc/require-* rules are off by default; only enabled rules and
+    // non-default overrides are specified here
+    files: ['**/*.{ts,tsx,js,jsx,mts,cts,mjs}'],
+    plugins: {
+      jsdoc,
+    },
+    rules: {
+      // JSDoc format and style rules (enforce when JSDoc is used)
+      'jsdoc/check-alignment': 'warn',
+      'jsdoc/check-indentation': 'warn',
+      'jsdoc/check-syntax': 'error',
+      'jsdoc/check-types': 'warn',
+      'jsdoc/empty-tags': 'error',
+      'jsdoc/no-bad-blocks': 'warn',
+      'jsdoc/no-defaults': 'warn',
+      'jsdoc/require-param-name': 'error',
+      'jsdoc/require-property-name': 'error',
+      'jsdoc/valid-types': 'error',
+
+      // Disable rules that conflict with TypeScript (these are NOT off by default)
+      'jsdoc/no-undefined-types': 'off', // TypeScript handles types
+      'jsdoc/require-returns-check': 'off', // TypeScript provides return types
+    },
+  },
+  {
+    // YAML configuration - enforce double quotes
+    files: ['**/*.yaml', '**/*.yml'],
+    ignores: ['**/pnpm-lock.yaml'],
+    languageOptions: {
+      parser: yamlParser,
+    },
+    plugins: {
+      yml: ymlPlugin,
+    },
+    rules: {
+      // Prefer double quotes over single quotes in YAML
+      'yml/quotes': [
+        'error',
+        {
+          prefer: 'double',
+          avoidEscape: true, // Allow single quotes only when escaping would be necessary
+        },
+      ],
+    },
+  },
+  {
+    // PNPM package.json validation
+    files: ['**/package.json'],
+    languageOptions: {
+      parser: jsoncParser,
+    },
+    plugins: {
+      pnpm: pnpmPlugin,
+    },
+    rules: {
+      'pnpm/json-valid-catalog': 'error',
+      'pnpm/json-prefer-workspace-settings': 'warn',
+      // Disable TypeScript rules that require type information for JSON files
+      '@typescript-eslint/consistent-type-imports': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+    },
+  },
+  {
+    // PNPM workspace YAML validation
+    files: ['**/pnpm-workspace.yaml', '**/pnpm-workspace.yml'],
+    languageOptions: {
+      parser: yamlParser,
+    },
+    plugins: {
+      pnpm: pnpmPlugin,
+    },
+    rules: {
+      'pnpm/yaml-no-unused-catalog-item': 'error',
+      'pnpm/yaml-no-duplicate-catalog-item': 'error',
+    },
+  },
+  {
+    // Config files - allow console (import rules handled in react.mjs which has import plugin)
+    files: [
+      '**/*.config.{js,ts,mjs}',
+      '**/eslint.config.{js,mjs}',
+      '**/vitest.config.{ts,js,mjs}',
+      '**/playwright.config.{ts,js,mjs}',
+    ],
+    rules: {
+      'no-console': 'off',
+    },
+  },
+  {
+    // Script files - relax security rules
+    files: ['**/scripts/**/*.{ts,js,mjs}'],
+    rules: {
+      'no-console': 'off',
+      'security/detect-non-literal-fs-filename': 'off',
+      'security/detect-non-literal-require': 'off',
+    },
+  },
+  {
+    // .mjs files - allow console for ESM scripts that may need fallback logging
+    // These files run directly in Node.js ESM and may use console as fallback
+    // when @od-oneapp/shared/logs/client/next cannot be imported (e.g., during build scripts)
+    files: ['**/*.mjs'],
+    rules: {
+      'no-console': 'off',
+    },
+  },
+  {
+    // ESLint config utilities - allow console for validation error fallback (e.g. create-validated-config)
+    files: ['**/eslint/utils/**'],
+    rules: {
+      'no-console': 'off',
+    },
+  },
+  {
+    // Environment validation files - console allowed for early validation warnings
+    // These run before @od-oneapp/observability is initialized
+    files: ['**/env.ts', '**/env.mts'],
+    rules: {
+      'no-console': 'off',
+    },
+  },
+  // Note: Type definition file rules (import/no-duplicates) are in react.mjs which has the import plugin
+);
+
+export default createValidatedConfig(config, 'base');

package/eslint/expo.mjs

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview ESLint configuration for Expo/React Native projects
+ *
+ * Extends React config and adds React Native specific rules and patterns.
+ * Optimized for Expo SDK and React Native development.
+ *
+ * **Features**:
+ * - React Native plugin rules
+ * - React Native accessibility props support
+ * - React 19.2 support (inherited from react.mjs)
+ * - React Native best practices (no inline styles, split platform components)
+ *
+ * **Use cases**:
+ * - Expo applications
+ * - React Native applications
+ * - Cross-platform mobile development
+ *
+ * @example
+ * ```javascript
+ * // eslint.config.mjs
+ * import expoConfig from '@od-oneapp/config/eslint/expo';
+ * export default expoConfig;
+ * ```
+ */
+
+import reactNative from 'eslint-plugin-react-native';
+import tseslint from 'typescript-eslint';
+
+import reactConfig from './react.mjs';
+import { createValidatedConfig } from './utils/create-validated-config.mjs';
+
+/**
+ * Expo/React Native ESLint configuration
+ *
+ * @type {import('typescript-eslint').ConfigArray}
+ */
+const config = tseslint.config(...reactConfig, {
+  files: ['**/*.{ts,tsx,js,jsx,mjs}'],
+  plugins: {
+    'react-native': reactNative,
+  },
+  // Note: React settings (version: 'detect') are inherited from react.mjs
+  rules: {
+    // React Native specific rules
+    'react-native/no-unused-styles': 'warn',
+    'react-native/split-platform-components': 'warn',
+    'react-native/no-inline-styles': 'warn',
+    'react-native/no-color-literals': 'warn',
+    'react-native/no-raw-text': 'warn',
+    'react-native/no-single-element-style-arrays': 'warn',
+
+    // Override React web-specific rules for React Native
+    'react/no-unknown-property': [
+      'error',
+      {
+        ignore: [
+          // React Native specific props
+          'accessibilityRole',
+          'accessibilityLabel',
+          'accessibilityHint',
+          'accessibilityState',
+          'accessibilityValue',
+          'accessibilityLiveRegion',
+          'accessibilityViewIsModal',
+          'accessibilityElementsHidden',
+          'testID',
+          'nativeID',
+          'collapsable',
+          'needsOffscreenAlphaCompositing',
+          'renderToHardwareTextureAndroid',
+          'importantForAccessibility',
+          'accessibilityIgnoresInvertColors',
+          'accessibilityElementsHidden',
+          'pointerEvents',
+          'removeClippedSubviews',
+          'shouldRasterizeIOS',
+          'onStartShouldSetResponder',
+          'onMoveShouldSetResponder',
+          'onStartShouldSetResponderCapture',
+          'onMoveShouldSetResponderCapture',
+          'onResponderGrant',
+          'onResponderMove',
+          'onResponderRelease',
+          'onResponderTerminate',
+          'onResponderTerminationRequest',
+          'elevation',
+          'hitSlop',
+        ],
+      },
+    ],
+
+    // React Native best practices
+    'react/jsx-no-leaked-render': 'off', // React Native handles this differently
+  },
+});
+
+export default createValidatedConfig(config, 'expo');

package/eslint/next-test.mjs

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Combined ESLint configuration for Next.js projects with test support
+ *
+ * Combines Next.js config with test config, filtering out conflicting TypeScript ESLint
+ * configs to avoid "Cannot redefine plugin" errors.
+ *
+ * **Use cases**:
+ * - Next.js projects that need test file linting
+ * - Single config for both app and test files
+ *
+ * **Note**: This is a convenience export. You can also combine manually:
+ * ```javascript
+ * import nextConfig from '@od-oneapp/config/eslint/next';
+ * import testConfig from '@od-oneapp/config/eslint/test';
+ * import { filterTypeScriptESLintConfigs } from '@od-oneapp/config/eslint/utils/filter-ts-eslint-configs';
+ * export default [...nextConfig, ...filterTypeScriptESLintConfigs(testConfig)];
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // eslint.config.mjs
+ * import nextTestConfig from '@od-oneapp/config/eslint/next-test';
+ * export default nextTestConfig;
+ * ```
+ */
+
+import nextConfig from './next.mjs';
+import testConfig from './test.mjs';
+import { createValidatedConfig } from './utils/create-validated-config.mjs';
+import { filterTypeScriptESLintConfigs } from './utils/filter-ts-eslint-configs.mjs';
+
+// Filter out TypeScript ESLint configs from testConfig since nextConfig (eslint-config-next) provides them
+// This avoids "Cannot redefine plugin" errors
+const testConfigWithoutTS = filterTypeScriptESLintConfigs(testConfig);
+
+/**
+ * Combined Next.js + Test ESLint configuration
+ *
+ * @type {import('typescript-eslint').ConfigArray}
+ */
+const config = [...nextConfig, ...testConfigWithoutTS];
+
+export default createValidatedConfig(config, 'next-test');

package/eslint/next.mjs

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview ESLint configuration for Next.js 16 projects
+ *
+ * Extends React config and integrates with `eslint-config-next` for Next.js-specific rules.
+ * Includes Core Web Vitals optimizations for Next.js 16 performance.
+ *
+ * **Features**:
+ * - Next.js 16 App Router rules
+ * - Core Web Vitals optimizations
+ * - React 19.2 support (inherited from react.mjs)
+ * - TypeScript ESLint (provided by eslint-config-next)
+ * - Import and JSX-a11y plugins (provided by eslint-config-next)
+ *
+ * **Note**: Filters out conflicting plugins from react.mjs to avoid "Cannot redefine plugin" errors.
+ * The Next.js config provides its own optimized versions of these plugins.
+ *
+ * @example
+ * ```javascript
+ * // eslint.config.mjs
+ * import nextConfig from '@od-oneapp/config/eslint/next';
+ * export default nextConfig;
+ * ```
+ */
+
+import nextMain from 'eslint-config-next';
+import nextVitals from 'eslint-config-next/core-web-vitals';
+import tseslint from 'typescript-eslint';
+
+import reactConfig from './react.mjs';
+import { createValidatedConfig } from './utils/create-validated-config.mjs';
+import { filterPluginsForNextJs } from './utils/filter-ts-eslint-configs.mjs';
+
+// Filter out plugin definitions and TypeScript ESLint configs from reactConfig
+// since nextMain (eslint-config-next) will provide them
+// This avoids "Cannot redefine plugin" errors
+const reactConfigWithoutPlugins = filterPluginsForNextJs(reactConfig);
+
+/**
+ * Next.js ESLint configuration
+ *
+ * @type {import('typescript-eslint').ConfigArray}
+ */
+const config = tseslint.config(
+  // Apply React config (without import/jsx-a11y plugins to avoid conflicts)
+  ...reactConfigWithoutPlugins,
+  // Main Next.js config - includes all Next.js rules, React rules, TypeScript rules, and Next.js plugin
+  // Next.js provides: react, react-hooks, import, jsx-a11y plugins with Next.js-optimized settings
+  ...nextMain,
+  // Additional Core Web Vitals rules for Next.js 16 performance optimization
+  // These enforce Web Vitals best practices specific to Next.js 16
+  ...nextVitals,
+  {
+    // Next.js 16 specific rule overrides and enhancements
+    rules: {
+      // Core Web Vitals optimizations for Next.js 16
+      '@next/next/no-html-link-for-pages': 'error',
+      '@next/next/no-img-element': 'error',
+
+      // Next.js 16 App Router specific rules
+      '@next/next/no-before-interactive-script-outside-document': 'error',
+      '@next/next/no-assign-module-variable': 'error',
+      '@next/next/no-head-element': 'error',
+
+      // Performance and best practices for Next.js 16
+      '@next/next/no-page-custom-font': 'warn',
+      '@next/next/no-unwanted-polyfillio': 'warn',
+    },
+    // Override default ignores of eslint-config-next
+    // Note: .storybook/** is not ignored here so it can be linted by the Storybook config
+    ignores: ['**/.next/**', '**/out/**', '**/build/**', '**/next-env.d.ts'],
+  },
+);
+
+export default createValidatedConfig(config, 'next');