@dimensional-innovations/tool-config 1.0.0

package/src/tools/eslint/index.js

@@ -0,0 +1,287 @@
+import js from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+import { autoDetect } from '../../detectors.js'
+
+import basePreset from './presets/base.js'
+import browserEnv from './presets/environments/browser.js'
+import nodeEnv from './presets/environments/node.js'
+import universalEnv from './presets/environments/universal.js'
+import createAngularPreset from './presets/frameworks/angular.js'
+import createNodePreset from './presets/frameworks/node.js'
+import createReactPreset from './presets/frameworks/react.js'
+import createVanillaPreset from './presets/frameworks/vanilla.js'
+import createVuePreset from './presets/frameworks/vue.js'
+import importsPreset from './presets/imports.js'
+import typescriptPreset from './presets/typescript.js'
+
+/**
+ * File patterns for all supported source file types
+ */
+const SOURCE_FILES = [
+  '**/*.js',
+  '**/*.ts',
+  '**/*.tsx',
+  '**/*.vue',
+  '**/*.jsx',
+  '**/*.svelte',
+  '**/*.astro'
+]
+
+/**
+ * Add framework-specific configuration to config array
+ * Supports lazy loading for Svelte, Solid, and Astro to avoid requiring optional peer dependencies
+ *
+ * @param {Array} config - ESLint flat config array to append framework presets to
+ * @param {string} framework - Framework name ('react' | 'vue' | 'svelte' | 'solid' | 'astro' | 'angular' | 'vanilla' | 'node')
+ * @returns {Promise<void>}
+ */
+async function addFrameworkConfig(config, framework) {
+  switch (framework) {
+    case 'react':
+      config.push(...createReactPreset())
+      break
+    case 'vue':
+      config.push(...createVuePreset())
+      break
+    case 'svelte': {
+      const { default: createSveltePreset } = await import('./presets/frameworks/svelte.js')
+      config.push(...createSveltePreset())
+      break
+    }
+    case 'solid': {
+      const { default: createSolidPreset } = await import('./presets/frameworks/solid.js')
+      config.push(...createSolidPreset())
+      break
+    }
+    case 'astro': {
+      const { default: createAstroPreset } = await import('./presets/frameworks/astro.js')
+      config.push(...createAstroPreset())
+      break
+    }
+    case 'vanilla':
+      config.push(...createVanillaPreset())
+      break
+    case 'node':
+      config.push(...createNodePreset())
+      break
+    case 'angular':
+      config.push(...createAngularPreset())
+      break
+    default:
+      console.warn(`⚠️  Unknown framework "${framework}", defaulting to vanilla JavaScript`)
+      config.push(...createVanillaPreset())
+      break
+  }
+}
+
+/**
+ * Get environment configuration based on detected or specified environment
+ * Returns globals and languageOptions for browser, node, or universal environments
+ *
+ * @param {string} environment - Environment type ('browser' | 'node' | 'universal')
+ * @returns {Object} Environment configuration object with languageOptions
+ */
+function getEnvironmentConfig(environment) {
+  switch (environment) {
+    case 'node':
+      return nodeEnv
+    case 'universal':
+      return universalEnv
+    case 'browser':
+    default:
+      return browserEnv
+  }
+}
+
+/**
+ * Add TypeScript configuration to config array
+ * Includes recommended TypeScript rules with relaxed settings for .d.ts and .js files
+ *
+ * @param {Array} config - ESLint flat config array to append TypeScript presets to
+ * @returns {void}
+ */
+function addTypeScriptConfig(config) {
+  config.push(...tseslint.configs.recommended)
+  config.push({
+    files: SOURCE_FILES,
+    ...typescriptPreset
+  })
+
+  config.push({
+    files: ['**/*.d.ts'],
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off'
+    }
+  })
+
+  config.push({
+    files: ['**/*.js'],
+    rules: {
+      '@typescript-eslint/no-var-requires': 'off'
+    }
+  })
+}
+
+/**
+ * Add test and script overrides to config array
+ * Relaxes rules for test files and CLI scripts, and applies user-provided rule overrides
+ *
+ * @param {Array} config - ESLint flat config array to append overrides to
+ * @param {Object} options - Configuration options containing user rule overrides
+ * @param {Object} [options.rules] - User-provided rule overrides
+ * @returns {void}
+ */
+function addOverrides(config, options) {
+  // Test files override
+  config.push({
+    files: ['tests/**/*.{js,ts,jsx,tsx,vue,svelte,astro}'],
+    rules: {
+      'no-console': 'off',
+      'max-lines-per-function': 'off',
+      complexity: 'off',
+      'max-statements': 'off',
+      'max-nested-callbacks': 'off',
+      'no-magic-numbers': 'off',
+      '@typescript-eslint/no-explicit-any': 'off'
+    }
+  })
+
+  // Node.js scripts override
+  config.push({
+    files: ['**/bin/**/*.js', '**/scripts/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...nodeEnv.languageOptions.globals
+      }
+    },
+    rules: {
+      'no-console': 'off',
+      'max-lines-per-function': 'off'
+    }
+  })
+
+  // User-provided rule overrides
+  if (options.rules && Object.keys(options.rules).length > 0) {
+    config.push({
+      files: SOURCE_FILES,
+      rules: options.rules
+    })
+  }
+}
+
+/**
+ * Create an ESLint flat config
+ *
+ * Supports: React, Vue.js, Svelte, Solid, Astro, Angular, Vanilla JS/TS, and auto-detection
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} [options.framework='auto'] - Framework: 'auto' | 'react' | 'vue' | 'svelte' | 'solid' | 'astro' | 'angular' | 'vanilla' | 'node'
+ * @param {string} [options.environment='auto'] - Environment: 'auto' | 'browser' | 'node' | 'universal'
+ * @param {boolean|string} [options.typescript='auto'] - TypeScript: 'auto' | true | false
+ * @param {string[]} [options.ignorePaths=[]] - Additional paths to ignore during linting
+ * @param {Object} [options.rules={}] - Additional rule overrides
+ * @param {string} [options.cwd] - Current working directory for detection
+ * @returns {Promise<Array>} ESLint flat config array
+ *
+ * @example
+ * // Zero config - auto-detects everything
+ * import { createEslintConfig } from '@dimensional-innovations/tool-config';
+ * export default await createEslintConfig();
+ *
+ * @example
+ * // Explicit configuration
+ * import { createEslintConfig } from '@dimensional-innovations/tool-config';
+ * export default await createEslintConfig({
+ *   framework: 'react',
+ *   environment: 'browser',
+ *   typescript: true
+ * });
+ *
+ * @example
+ * // With custom rules
+ * import { createEslintConfig } from '@dimensional-innovations/tool-config';
+ * export default await createEslintConfig({
+ *   rules: {
+ *     'no-console': 'off'
+ *   }
+ * });
+ */
+export async function createEslintConfig(options = {}) {
+  const cwd = options.cwd || process.cwd()
+  const detected = autoDetect(cwd)
+
+  const framework =
+    options.framework === 'auto' || !options.framework ? detected.framework : options.framework
+  const environment =
+    options.environment === 'auto' || !options.environment
+      ? detected.environment
+      : options.environment
+  const typescript =
+    options.typescript === 'auto' || options.typescript === undefined
+      ? detected.typescript
+      : options.typescript
+
+  console.log(
+    `📦 ESLint Config: ${framework} | ${environment} | TypeScript: ${typescript ? 'Yes' : 'No'}`
+  )
+
+  if (framework === 'angular') {
+    console.warn(
+      '\n⚠️  Angular detected. This package provides basic TypeScript linting.\n' +
+        '   For Angular-specific rules, install: @angular-eslint/eslint-plugin\n' +
+        '   See: https://github.com/angular-eslint/angular-eslint\n'
+    )
+  }
+
+  const defaultIgnorePaths = [
+    '**/node_modules/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/.next/**',
+    '**/.nuxt/**'
+  ]
+  const allIgnorePaths = [...defaultIgnorePaths, ...(options.ignorePaths || [])]
+
+  const config = []
+
+  // 1. Ignore paths
+  config.push({ ignores: allIgnorePaths })
+
+  // 2. ESLint recommended rules
+  config.push(js.configs.recommended)
+
+  // 3. TypeScript configuration
+  if (typescript) {
+    addTypeScriptConfig(config)
+  }
+
+  // 4. Environment configuration
+  const envConfig = getEnvironmentConfig(environment)
+  config.push({
+    files: SOURCE_FILES,
+    ...envConfig
+  })
+
+  // 5. Base JavaScript rules
+  config.push({
+    files: SOURCE_FILES,
+    ...basePreset
+  })
+
+  // 6. Import/export rules
+  config.push({
+    files: SOURCE_FILES,
+    ...importsPreset
+  })
+
+  // 7. Framework-specific configuration
+  await addFrameworkConfig(config, framework)
+
+  // 8. Test files and script overrides
+  addOverrides(config, options)
+
+  return config
+}
+
+export default createEslintConfig

package/src/tools/eslint/presets/base.js

@@ -0,0 +1,82 @@
+/**
+ * Base JavaScript rules that apply to all projects
+ * These are framework-agnostic and environment-agnostic
+ */
+export default {
+  rules: {
+    // ============================================================
+    // MODERN JAVASCRIPT RULES
+    // Best practices for ES2015+ code
+    // Documentation: https://eslint.org/docs/rules/
+    // ============================================================
+
+    // Console and debugging
+    'no-console': ['warn', { allow: ['warn', 'error'] }], // Warn on console.log but allow console.warn/error for logging
+    'no-debugger': 'warn', // Warn on debugger statements (should be removed before commit)
+    'no-alert': 'error', // Disallow alert/confirm/prompt (use proper UI)
+
+    // Modern syntax preferences
+    'prefer-const': 'error', // Use const for variables that are never reassigned
+    'no-var': 'error', // Use let/const instead of var
+    'prefer-arrow-callback': 'error', // Use arrow functions for callbacks
+    'prefer-template': 'error', // Use template literals instead of string concatenation
+    'prefer-destructuring': [
+      'error',
+      {
+        array: true,
+        object: true
+      },
+      {
+        enforceForRenamedProperties: false
+      }
+    ], // Use destructuring where possible
+    'prefer-rest-params': 'error', // Use rest parameters instead of arguments object
+    'prefer-spread': 'error', // Use spread operator instead of .apply()
+    'object-shorthand': 'error', // Use object shorthand syntax {x} instead of {x: x}
+    'arrow-body-style': ['error', 'as-needed'], // Omit braces when possible in arrow functions
+
+    // Code quality
+    eqeqeq: ['error', 'always'], // Always use === and !== instead of == and !=
+    'no-duplicate-imports': 'error', // Prevent duplicate imports from same module
+    'no-useless-computed-key': 'error', // Disallow unnecessary computed property keys
+    'no-useless-constructor': 'error', // Disallow unnecessary constructors
+    'no-useless-rename': 'error', // Disallow renaming import/export/destructured assignments to same name
+    'no-nested-ternary': 'error', // Disallow nested ternary expressions (hard to read)
+    'no-unneeded-ternary': 'error', // Disallow ternary operators when simpler alternatives exist
+    'prefer-object-spread': 'error', // Use object spread instead of Object.assign
+
+    // Async/Promise best practices
+    'no-return-await': 'error', // Disallow unnecessary return await
+    'require-await': 'error', // Disallow async functions that don't use await
+    'no-promise-executor-return': 'error', // Disallow returning values from Promise executor functions
+
+    // ============================================================
+    // CODE QUALITY & COMPLEXITY
+    // Maintainability and readability rules
+    // Documentation: https://eslint.org/docs/rules/
+    // ============================================================
+
+    // Complexity (warnings to identify areas needing refactoring)
+    complexity: ['warn', 15], // Warn on high cyclomatic complexity
+    'max-depth': ['warn', 4], // Warn on deeply nested blocks
+    'max-lines': ['warn', 500], // Warn on files exceeding 500 lines
+    'max-lines-per-function': [
+      'warn',
+      {
+        max: 100,
+        skipBlankLines: true,
+        skipComments: true
+      }
+    ], // Warn on functions exceeding 100 lines
+    'max-params': ['warn', 4], // Warn on functions with more than 4 parameters
+
+    // Comments
+    'spaced-comment': [
+      'error',
+      'always',
+      {
+        markers: ['/']
+      }
+    ] // Require space after // or /*
+  }
+}

package/src/tools/eslint/presets/environments/browser.js

@@ -0,0 +1,16 @@
+import globals from 'globals'
+
+/**
+ * Browser environment configuration
+ * Adds browser global variables (window, document, etc.)
+ * ECMAScript 2025 (ES2025) support
+ */
+export default {
+  languageOptions: {
+    ecmaVersion: 2025,
+    sourceType: 'module',
+    globals: {
+      ...globals.browser
+    }
+  }
+}

package/src/tools/eslint/presets/environments/node.js

@@ -0,0 +1,21 @@
+import globals from 'globals'
+
+/**
+ * Node.js environment configuration
+ * Adds Node.js global variables (process, __dirname, require, etc.)
+ * ECMAScript 2025 (ES2025) support
+ */
+export default {
+  languageOptions: {
+    ecmaVersion: 2025,
+    sourceType: 'module',
+    globals: {
+      ...globals.node
+    }
+  },
+  rules: {
+    // Node.js-specific rule adjustments
+    'no-console': 'off', // Console is normal in Node.js
+    '@typescript-eslint/no-var-requires': 'off' // Allow require() in .js files
+  }
+}

package/src/tools/eslint/presets/environments/universal.js

@@ -0,0 +1,18 @@
+import globals from 'globals'
+
+/**
+ * Universal environment configuration
+ * Combines both browser and Node.js globals for fullstack apps
+ * Useful for: Astro, Electron, fullstack monorepos
+ * ECMAScript 2025 (ES2025) support
+ */
+export default {
+  languageOptions: {
+    ecmaVersion: 2025,
+    sourceType: 'module',
+    globals: {
+      ...globals.browser,
+      ...globals.node
+    }
+  }
+}

package/src/tools/eslint/presets/frameworks/angular.js

@@ -0,0 +1,74 @@
+/**
+ * Angular configuration (basic TypeScript linting)
+ *
+ * Note: This provides basic TypeScript linting for Angular projects.
+ * For Angular-specific template and component rules, install:
+ * @angular-eslint/eslint-plugin
+ *
+ * See: https://github.com/angular-eslint/angular-eslint
+ */
+export default function createAngularPreset() {
+  return [
+    {
+      files: ['**/*.ts'],
+      rules: {
+        // ============================================================
+        // ANGULAR-FRIENDLY TYPESCRIPT RULES
+        // Basic rules that work well with Angular patterns
+        // ============================================================
+
+        // Angular uses decorators extensively
+        '@typescript-eslint/no-extraneous-class': 'off',
+
+        // Angular components often have empty constructors for DI
+        '@typescript-eslint/no-empty-function': [
+          'error',
+          {
+            allow: ['constructors']
+          }
+        ],
+
+        // Angular uses ! for definite assignment (properties set by Angular)
+        '@typescript-eslint/no-non-null-assertion': 'warn',
+
+        // Angular services and components use 'any' in some cases
+        '@typescript-eslint/no-explicit-any': 'warn',
+
+        // Parameter properties are common in Angular (constructor(private foo: Foo))
+        '@typescript-eslint/parameter-properties': 'off',
+        '@typescript-eslint/explicit-member-accessibility': 'off',
+
+        // Angular uses both interfaces and types
+        '@typescript-eslint/consistent-type-definitions': 'off',
+
+        // Naming conventions for Angular
+        '@typescript-eslint/naming-convention': [
+          'error',
+          {
+            selector: 'default',
+            format: ['camelCase'],
+            leadingUnderscore: 'allow',
+            trailingUnderscore: 'allow'
+          },
+          {
+            selector: 'variable',
+            format: ['camelCase', 'UPPER_CASE', 'PascalCase'],
+            leadingUnderscore: 'allow'
+          },
+          {
+            selector: 'typeLike',
+            format: ['PascalCase']
+          },
+          {
+            selector: 'enumMember',
+            format: ['PascalCase', 'UPPER_CASE']
+          },
+          {
+            selector: 'property',
+            format: null // Allow any format for properties (Angular templates use various patterns)
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/tools/eslint/presets/frameworks/astro.js

@@ -0,0 +1,38 @@
+import { configs } from 'eslint-plugin-astro'
+
+/**
+ * Astro framework configuration
+ * Rules for Astro components and island architecture
+ *
+ * Rules organized by category:
+ * - Component best practices
+ * - Island architecture
+ * - Template syntax
+ * - Accessibility
+ */
+export default function createAstroPreset() {
+  return [
+    ...configs.recommended,
+    ...configs['jsx-a11y-recommended'],
+    {
+      files: ['**/*.astro'],
+      rules: {
+        // Component Best Practices (5 rules)
+        'astro/no-conflict-set-directives': 'error', // Avoid conflicting set directives
+        'astro/no-unused-define-vars-in-style': 'error', // Remove unused CSS variables
+        'astro/no-deprecated-astro-canonicalurl': 'error', // Use new canonical URL API
+        'astro/no-deprecated-astro-fetchcontent': 'error', // Use new content collections
+        'astro/no-deprecated-astro-resolve': 'error', // Use new module resolution
+
+        // Template Syntax (4 rules)
+        'astro/valid-compile': 'error', // Ensure valid Astro syntax
+        'astro/no-set-html-directive': 'warn', // Warn about XSS risk
+        'astro/semi': ['error', 'always'], // Consistent semicolons in frontmatter
+        'astro/prefer-class-list-directive': 'error' // Use class:list over className
+
+        // Accessibility (included from jsx-a11y-recommended preset)
+        // - alt-text, click-events-have-key-events, etc.
+      }
+    }
+  ]
+}

package/src/tools/eslint/presets/frameworks/node.js

@@ -0,0 +1,57 @@
+/**
+ * Node.js backend configuration
+ * Conservative rules for Node.js/Express/Fastify backend services
+ */
+export default function createNodePreset() {
+  return [
+    {
+      files: ['**/*.js', '**/*.ts', '**/*.mjs'],
+      rules: {
+        // ============================================================
+        // NODE.JS BACKEND RULES
+        // Best practices for server-side JavaScript/TypeScript
+        // ============================================================
+
+        // Console usage is normal in Node.js
+        'no-console': 'off',
+
+        // Process and __dirname are standard in Node
+        'no-process-env': 'off',
+        'no-process-exit': 'warn',
+
+        // Async patterns
+        'no-async-promise-executor': 'error',
+        'require-atomic-updates': 'error',
+
+        // Error handling
+        'no-throw-literal': 'error',
+        'prefer-promise-reject-errors': 'error',
+
+        // Node.js specific
+        'callback-return': 'off', // Modern Node uses async/await
+        'handle-callback-err': 'off', // Modern Node uses async/await
+        'no-mixed-requires': 'off', // ES modules don't have this issue
+        'no-new-require': 'error',
+        'no-path-concat': 'error', // Use path.join() instead
+
+        // Security
+        'no-eval': 'error',
+        'no-implied-eval': 'error',
+        'no-new-func': 'error',
+
+        // Best practices for backend
+        'no-unused-vars': [
+          'error',
+          {
+            args: 'after-used',
+            argsIgnorePattern: '^_',
+            varsIgnorePattern: '^_'
+          }
+        ],
+
+        // Allow both require and import
+        '@typescript-eslint/no-var-requires': 'off'
+      }
+    }
+  ]
+}

package/src/tools/eslint/presets/frameworks/react.js

@@ -0,0 +1,76 @@
+import react from 'eslint-plugin-react'
+import reactHooks from 'eslint-plugin-react-hooks'
+
+/**
+ * React configuration (conservative)
+ * Includes React + React Hooks plugins with essential rules
+ */
+export default function createReactPreset() {
+  return [
+    // React recommended configuration
+    react.configs.flat.recommended,
+    react.configs.flat['jsx-runtime'], // Disable React-in-scope for React 17+
+
+    // React Hooks rules
+    {
+      files: ['**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx'],
+      plugins: {
+        'react-hooks': reactHooks
+      },
+      rules: reactHooks.configs.recommended.rules
+    },
+
+    // Custom opinionated React rules
+    {
+      files: ['**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx'],
+      settings: {
+        react: {
+          version: 'detect' // Automatically detect React version
+        }
+      },
+      rules: {
+        // ============================================================
+        // REACT RULES (Conservative - Essential Only)
+        // React best practices for modern React 17+
+        // Documentation: https://github.com/jsx-eslint/eslint-plugin-react
+        // ============================================================
+
+        // Modern React (17+) adjustments
+        'react/react-in-jsx-scope': 'off', // Not needed in React 17+ with new JSX transform
+        'react/jsx-uses-react': 'off', // Not needed in React 17+ with new JSX transform
+
+        // TypeScript integration
+        'react/prop-types': 'off', // TypeScript handles prop validation
+
+        // JSX best practices
+        'react/jsx-uses-vars': 'error', // Prevent variables used in JSX being marked as unused
+        'react/jsx-curly-brace-presence': ['error', { props: 'never', children: 'never' }], // Use strings when possible: prop="value" not prop={"value"}
+        'react/self-closing-comp': 'error', // Use <Component /> instead of <Component></Component>
+        'react/jsx-boolean-value': ['error', 'never'], // Use prop instead of prop={true}
+        'react/jsx-fragments': ['error', 'syntax'], // Use <> instead of <Fragment>
+        'react/jsx-no-useless-fragment': 'error', // Disallow unnecessary fragments
+
+        // Component definition
+        'react/function-component-definition': [
+          'error',
+          {
+            namedComponents: 'arrow-function', // const Component = () => ...
+            unnamedComponents: 'arrow-function'
+          }
+        ],
+
+        // Hooks (enforced by react-hooks plugin)
+        // - react-hooks/rules-of-hooks: error
+        // - react-hooks/exhaustive-deps: warn
+
+        // Best practices
+        'react/no-array-index-key': 'warn', // Warn when using array index as key (can cause issues)
+        'react/jsx-key': 'error', // Require key prop in iterators
+        'react/no-children-prop': 'error', // Prevent passing children as props
+        'react/no-danger': 'warn', // Warn on dangerouslySetInnerHTML (XSS risk)
+        'react/no-deprecated': 'error', // Prevent usage of deprecated methods
+        'react/no-unknown-property': 'error' // Prevent usage of unknown DOM properties
+      }
+    }
+  ]
+}