@dimensional-innovations/tool-config 1.0.0

package/src/tools/stylelint/README.md

@@ -0,0 +1,425 @@
+# Stylelint Configuration
+
+Framework-aware Stylelint configuration for CSS quality linting across all supported frameworks.
+
+## Philosophy
+
+This Stylelint configuration focuses on **CSS quality**, not formatting:
+
+- **Quality Rules**: Catches errors, enforces best practices, prevents common mistakes
+- **Formatting**: Left to Prettier (never conflicts)
+- **Framework-Aware**: Automatically applies framework-specific rules
+- **Zero Config**: Works out of the box with sensible defaults
+
+**Key Principle**: Stylelint is for CSS files and component styles (Vue `<style>`, Svelte `<style>`). CSS-in-JS (styled-components, emotion) should use ESLint plugins instead.
+
+## Installation
+
+The Stylelint tool and core config are included as dependencies. For Vue projects, install optional peer dependencies:
+
+```bash
+# Vue projects only
+npm install --save-dev stylelint-config-standard-vue postcss-html
+
+# Svelte projects need postcss-html for component parsing
+npm install --save-dev postcss-html
+```
+
+## Usage
+
+### Auto-Detection (Recommended)
+
+```javascript
+// stylelint.config.js
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('stylelint')
+```
+
+The factory automatically detects your framework and applies appropriate rules.
+
+### Explicit Framework
+
+```javascript
+// stylelint.config.js
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('stylelint', {
+  framework: 'vue' // react, vue, svelte, solid, astro, angular, vanilla, node
+})
+```
+
+### With Custom Rules
+
+```javascript
+// stylelint.config.js
+import { createConfig } from '@dimensional-innovations/tool-config'
+
+export default createConfig('stylelint', {
+  rules: {
+    'color-hex-length': 'long',
+    'max-nesting-depth': 4
+  }
+})
+```
+
+## Framework Support
+
+| Framework   | Support Level | Features                                                           |
+| ----------- | ------------- | ------------------------------------------------------------------ |
+| **Vue**     | Full          | Scoped styles, `:deep()`, `:global()`, `:slotted()` pseudo-classes |
+| **Svelte**  | Full          | Component styles, `:global()` pseudo-class                         |
+| **React**   | CSS Modules   | `:global()`, `:local()`, `:export`, `:import` pseudo-classes       |
+| **Solid**   | CSS Modules   | Same as React (CSS Modules support)                                |
+| **Angular** | Base          | Standard CSS linting                                               |
+| **Astro**   | Base          | Standard CSS linting                                               |
+| **Vanilla** | Full          | Standard CSS linting                                               |
+| **Node.js** | N/A           | Not applicable (no CSS in Node.js backends)                        |
+
+### When to Use Stylelint
+
+**Use Stylelint for:**
+
+- Separate CSS files (`styles.css`)
+- Vue Single File Components (`<style>` blocks)
+- Svelte components (`<style>` blocks)
+- CSS Modules (`.module.css`)
+- Sass/SCSS files
+
+**Don't use Stylelint for:**
+
+- CSS-in-JS (styled-components, emotion) → Use ESLint plugins
+- Inline styles in JSX → Use ESLint plugins
+- Tailwind classes → Not linted (utility-first)
+
+## Base Configuration
+
+All frameworks start with these base rules:
+
+### Color Rules
+
+- `color-hex-length`: Prefer short hex colors (`#fff` not `#ffffff`)
+- `color-named`: Disallow named colors (use hex/rgb instead)
+
+### Property Rules
+
+- `declaration-block-no-redundant-longhand-properties`: Use shorthands where possible
+- `shorthand-property-no-redundant-values`: Avoid redundant values in shorthands
+
+### Selector Rules
+
+- `selector-max-id`: No ID selectors (use classes)
+- `selector-no-qualifying-type`: Don't qualify selectors with type (`div.foo` → `.foo`)
+- `selector-class-pattern`: Enforce BEM or kebab-case naming
+
+### Structure Rules
+
+- `max-nesting-depth`: Maximum 3 levels of nesting
+- `no-descending-specificity`: Disabled (too strict for real-world CSS)
+
+### Tailwind Support
+
+Automatically ignores Tailwind at-rules:
+
+- `@tailwind`
+- `@apply`
+- `@variants`
+- `@responsive`
+- `@screen`
+
+## Framework-Specific Features
+
+### Vue (Scoped Styles)
+
+```vue
+<style scoped>
+/* Standard scoped styles work */
+.button {
+}
+
+/* Deep selectors supported */
+:deep(.child) {
+}
+:global(.utility) {
+}
+:slotted(span) {
+}
+</style>
+```
+
+**Configuration**: Extends `stylelint-config-standard-vue`, uses `postcss-html` parser.
+
+### Svelte (Component Styles)
+
+```svelte
+<style>
+/* Component-scoped by default */
+.button { }
+
+/* Global styles supported */
+:global(.utility) { }
+</style>
+```
+
+**Configuration**: Uses `postcss-html` parser for `.svelte` files.
+
+### React/Solid (CSS Modules)
+
+```css
+/* styles.module.css */
+.button {
+}
+
+:global(.utility) {
+}
+:local(.scoped) {
+}
+
+/* Exports for JavaScript */
+:export {
+  primaryColor: blue;
+}
+```
+
+**Configuration**: Supports CSS Modules pseudo-classes (`:global`, `:local`, `:export`, `:import`).
+
+### Angular/Astro/Vanilla
+
+Standard CSS linting with base rules. No framework-specific features needed.
+
+## Package.json Scripts
+
+Add these scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "style": "stylelint '**/*.css'",
+    "style:fix": "stylelint '**/*.css' --fix"
+  }
+}
+```
+
+### Framework-Specific Patterns
+
+**Vue**:
+
+```json
+{
+  "scripts": {
+    "style": "stylelint '**/*.css' '**/*.vue'",
+    "style:fix": "stylelint '**/*.css' '**/*.vue' --fix"
+  }
+}
+```
+
+**Svelte**:
+
+```json
+{
+  "scripts": {
+    "style": "stylelint '**/*.css' '**/*.svelte'",
+    "style:fix": "stylelint '**/*.css' '**/*.svelte' --fix"
+  }
+}
+```
+
+**React/Angular/Vanilla**:
+
+```json
+{
+  "scripts": {
+    "style": "stylelint '**/*.css'",
+    "style:fix": "stylelint '**/*.css' --fix'
+  }
+}
+```
+
+## Integration with Other Tools
+
+### Stylelint + Prettier
+
+No conflicts! They work together perfectly:
+
+- **Stylelint**: CSS quality (errors, best practices)
+- **Prettier**: CSS formatting (indentation, line breaks, spacing)
+
+Run them sequentially:
+
+```bash
+npm run style && npm run prettier:fix
+```
+
+### Stylelint + ESLint
+
+No conflicts! Different file types:
+
+- **ESLint**: JavaScript/TypeScript files
+- **Stylelint**: CSS files and component styles
+- **CSS-in-JS**: Use ESLint plugins (not Stylelint)
+
+### VSCode Integration
+
+Install the Stylelint extension:
+
+```json
+{
+  "stylelint.validate": ["css", "scss", "vue", "svelte"],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.stylelint": "explicit"
+  }
+}
+```
+
+## Common Overrides
+
+### Allow Deeper Nesting
+
+```javascript
+export default createConfig('stylelint', {
+  rules: {
+    'max-nesting-depth': 5
+  }
+})
+```
+
+### Allow ID Selectors
+
+```javascript
+export default createConfig('stylelint', {
+  rules: {
+    'selector-max-id': 2 // Allow up to 2 IDs
+  }
+})
+```
+
+### Custom Class Naming Pattern
+
+```javascript
+export default createConfig('stylelint', {
+  rules: {
+    'selector-class-pattern': '^[a-z][a-zA-Z0-9]+$' // camelCase only
+  }
+})
+```
+
+### Disable Specific Rule
+
+```javascript
+export default createConfig('stylelint', {
+  rules: {
+    'color-named': null // Allow named colors
+  }
+})
+```
+
+## Troubleshooting
+
+### "Cannot find module 'stylelint-config-standard-vue'"
+
+**Vue projects only**: Install the optional peer dependency:
+
+```bash
+npm install --save-dev stylelint-config-standard-vue postcss-html
+```
+
+### "Cannot find module 'postcss-html'"
+
+**Vue/Svelte projects**: Install the parser:
+
+```bash
+npm install --save-dev postcss-html
+```
+
+### Stylelint Not Linting .vue Files
+
+Make sure your script includes `.vue` files:
+
+```json
+{
+  "scripts": {
+    "style": "stylelint '**/*.css' '**/*.vue'"
+  }
+}
+```
+
+### Conflicts with Prettier
+
+This shouldn't happen! Our Stylelint config focuses on quality, not formatting. If you encounter conflicts:
+
+1. Check that Prettier is formatting CSS (it should be)
+2. Disable formatting-related Stylelint rules:
+   ```javascript
+   export default createConfig('stylelint', {
+     rules: {
+       indentation: null,
+       'string-quotes': null
+     }
+   })
+   ```
+
+### "Unknown rule" Errors
+
+Make sure you're using Stylelint 16+:
+
+```bash
+npm install --save-dev stylelint@^16.0.0
+```
+
+## Rule Philosophy
+
+### Error vs Warning
+
+**Error (Red)**: Will break your CSS or violate critical best practices
+
+- `color-named`: Named colors are unreliable across browsers
+- `selector-max-id`: IDs have high specificity and cause maintenance issues
+- `max-nesting-depth`: Deep nesting makes CSS hard to maintain
+
+**Warning (Yellow)**: Not used in this config (all rules are errors)
+
+**Off**: Rule disabled (conflicts with Prettier or too opinionated)
+
+### Why We Don't Use Warnings
+
+Warnings create ambiguity. Either something is wrong (error) or it's acceptable (off). Our approach:
+
+- **Error**: Fix this (quality/correctness issue)
+- **Off**: We don't care about this (formatting/style)
+
+## Examples
+
+See working examples in the `examples/` directory:
+
+- [examples/vue-app/](../../examples/vue-app/) - Vue 3 with scoped styles
+- [examples/svelte-app/](../../examples/svelte-app/) - Svelte 5 with component styles
+- [examples/react-app/](../../examples/react-app/) - React with CSS Modules
+- [examples/angular-app/](../../examples/angular-app/) - Angular with standard CSS
+- [examples/vanilla-js/](../../examples/vanilla-js/) - Vanilla JS with standard CSS
+
+## API Reference
+
+### createConfig(tool, options)
+
+**Parameters**:
+
+- `tool` (string): Must be `'stylelint'`
+- `options` (object):
+  - `framework` (string): `'auto'` (default) | `'react'` | `'vue'` | `'svelte'` | `'solid'` | `'astro'` | `'angular'` | `'vanilla'` | `'node'`
+  - `cwd` (string): Working directory for auto-detection (default: `process.cwd()`)
+  - `rules` (object): Rule overrides
+  - `extends` (string|array): Additional configs to extend
+  - `overrides` (array): File-specific overrides
+
+**Returns**: Stylelint configuration object
+
+## Related Documentation
+
+- [Stylelint Official Docs](https://stylelint.io/)
+- [stylelint-config-standard](https://github.com/stylelint/stylelint-config-standard)
+- [stylelint-config-standard-vue](https://github.com/ota-meshi/stylelint-config-standard-vue)
+- [postcss-html](https://github.com/gucong3000/postcss-html)
+
+## License
+
+MIT

package/src/tools/stylelint/index.js

@@ -0,0 +1,191 @@
+/**
+ * Stylelint configuration factory
+ *
+ * Creates Stylelint configurations with framework-aware defaults for CSS linting.
+ *
+ * Note: Stylelint is for CSS files and component styles (Vue, Svelte).
+ * CSS-in-JS (React styled-components, emotion) should use ESLint plugins instead.
+ */
+
+import { autoDetect, detectCssType } from '../../detectors.js'
+
+import basePreset from './presets/base.js'
+import cssModulesPreset from './presets/css-modules.js'
+import reactPreset from './presets/frameworks/react.js'
+import sveltePreset from './presets/frameworks/svelte.js'
+import vuePreset from './presets/frameworks/vue.js'
+import scssPreset from './presets/scss.js'
+import tailwindPreset from './presets/tailwind.js'
+
+/**
+ * Merge framework preset into config
+ * @param {Object} config - Base config
+ * @param {Object} preset - Framework preset
+ * @returns {void}
+ */
+function mergePreset(config, preset) {
+  if (preset.extends) {
+    config.extends = [...(config.extends || []), ...preset.extends]
+  }
+  if (preset.overrides) {
+    config.overrides = [...(config.overrides || []), ...preset.overrides]
+  }
+  if (preset.rules) {
+    config.rules = { ...config.rules, ...preset.rules }
+  }
+}
+
+/**
+ * Apply user overrides to config
+ * @param {Object} config - Current config
+ * @param {Object} userOverrides - User-provided overrides
+ * @returns {void}
+ */
+function applyUserOverrides(config, userOverrides) {
+  // Handle arrays (extends, plugins, overrides)
+  if (userOverrides.extends) {
+    const userExtends = Array.isArray(userOverrides.extends)
+      ? userOverrides.extends
+      : [userOverrides.extends]
+    config.extends = [...(config.extends || []), ...userExtends]
+    delete userOverrides.extends
+  }
+  if (userOverrides.plugins) {
+    const userPlugins = Array.isArray(userOverrides.plugins)
+      ? userOverrides.plugins
+      : [userOverrides.plugins]
+    config.plugins = [...(config.plugins || []), ...userPlugins]
+    delete userOverrides.plugins
+  }
+  if (userOverrides.overrides) {
+    const userOverridesArray = Array.isArray(userOverrides.overrides)
+      ? userOverrides.overrides
+      : [userOverrides.overrides]
+    config.overrides = [...(config.overrides || []), ...userOverridesArray]
+    delete userOverrides.overrides
+  }
+  if (userOverrides.rules) {
+    config.rules = { ...config.rules, ...userOverrides.rules }
+    delete userOverrides.rules
+  }
+
+  // Merge remaining overrides
+  Object.assign(config, userOverrides)
+}
+
+/**
+ * Create a Stylelint configuration
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} [options.framework='auto'] - Framework to configure for
+ * @param {string|Object} [options.cssType='auto'] - CSS type ('auto', 'css', 'scss', or detection object)
+ * @param {string} [options.cwd=process.cwd()] - Working directory for auto-detection
+ * @param {Object} [options.rules] - User rule overrides
+ * @param {Array|string} [options.extends] - Additional configs to extend
+ * @param {Array} [options.overrides] - File-specific overrides
+ * @returns {Object} Stylelint configuration object
+ *
+ * @example
+ * // Auto-detect framework
+ * export default createStylelintConfig();
+ *
+ * @example
+ * // Explicit framework
+ * export default createStylelintConfig({ framework: 'vue' });
+ *
+ * @example
+ * // Explicit CSS type
+ * export default createStylelintConfig({ cssType: 'scss' });
+ *
+ * @example
+ * // With overrides
+ * export default createStylelintConfig({
+ *   framework: 'vue',
+ *   cssType: 'scss',
+ *   rules: {
+ *     'color-hex-length': 'long'
+ *   }
+ * });
+ */
+export function createStylelintConfig(options = {}) {
+  const {
+    framework: explicitFramework = 'auto',
+    cssType: explicitCssType = 'auto',
+    cwd = process.cwd(),
+    ...userOverrides
+  } = options
+
+  // Auto-detect framework if needed
+  const framework = explicitFramework === 'auto' ? autoDetect(cwd).framework : explicitFramework
+
+  // Auto-detect CSS type if needed
+  const cssType = explicitCssType === 'auto' ? detectCssType(cwd) : explicitCssType
+
+  // Start with appropriate base configuration (SCSS or plain CSS)
+  const config =
+    cssType?.preprocessor === 'scss' || cssType === 'scss'
+      ? { ...scssPreset, customSyntax: 'postcss-scss' }
+      : { ...basePreset }
+
+  // Apply Tailwind preset if detected
+  if (cssType?.tailwind) {
+    mergePreset(config, tailwindPreset)
+  }
+
+  // CSS Modules support (for React/Next.js projects)
+  if ((framework === 'react' || framework === 'solid') && !cssType?.tailwind) {
+    mergePreset(config, cssModulesPreset)
+  }
+
+  // Build CSS type description
+  let cssTypeDesc = cssType?.preprocessor === 'scss' ? 'SCSS' : 'CSS'
+  if (cssType?.tailwind) cssTypeDesc += ' + Tailwind'
+  if ((framework === 'react' || framework === 'solid') && !cssType?.tailwind) {
+    cssTypeDesc += ' Modules'
+  }
+
+  // Apply framework-specific preset
+  switch (framework) {
+    case 'vue': {
+      mergePreset(config, vuePreset)
+      console.warn(`🎨 Stylelint: Detected Vue.js - linting .vue component styles (${cssTypeDesc})`)
+      break
+    }
+
+    case 'svelte': {
+      mergePreset(config, sveltePreset)
+      console.warn(
+        `🎨 Stylelint: Detected Svelte - linting .svelte component styles (${cssTypeDesc})`
+      )
+      break
+    }
+
+    case 'react':
+    case 'solid': {
+      mergePreset(config, reactPreset)
+      console.warn(
+        `🎨 Stylelint: Detected ${framework} - linting ${cssTypeDesc} (CSS-in-JS uses ESLint)`
+      )
+      break
+    }
+
+    case 'angular':
+    case 'node':
+    case 'vanilla':
+    case 'astro': {
+      console.warn(`🎨 Stylelint: Detected ${framework} - linting ${cssTypeDesc} files`)
+      break
+    }
+
+    default: {
+      console.warn(`⚠️  Unknown framework "${framework}", using base ${cssTypeDesc} linting`)
+    }
+  }
+
+  // Apply user overrides
+  applyUserOverrides(config, userOverrides)
+
+  return config
+}
+
+export default createStylelintConfig

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

@@ -0,0 +1,50 @@
+/**
+ * Base Stylelint preset
+ *
+ * Standard CSS linting rules for all projects.
+ * Focuses on code quality and best practices, NOT formatting (that's Prettier's job).
+ *
+ * Key principles:
+ * - Use modern CSS practices
+ * - Avoid common mistakes
+ * - Maintain consistency
+ * - Don't fight with Prettier
+ */
+
+export default {
+  extends: ['stylelint-config-standard'],
+
+  rules: {
+    // Color rules
+    'color-hex-length': 'short',
+    'color-named': 'never',
+
+    // Property rules
+    'declaration-block-no-redundant-longhand-properties': true,
+    'shorthand-property-no-redundant-values': true,
+
+    // Selector rules
+    'selector-max-id': 0,
+    'selector-no-qualifying-type': true,
+    'selector-class-pattern': [
+      '^[a-z]([a-z0-9-]+)?(__([a-z0-9]+-?)+)?(--([a-z0-9]+-?)+){0,2}$',
+      {
+        message: 'Expected class selector to be kebab-case or BEM format'
+      }
+    ],
+
+    // Nesting
+    'max-nesting-depth': 3,
+
+    // Specificity
+    'no-descending-specificity': null,
+
+    // At-rules
+    'at-rule-no-unknown': [
+      true,
+      {
+        ignoreAtRules: ['tailwind', 'apply', 'variants', 'responsive', 'screen']
+      }
+    ]
+  }
+}

package/src/tools/stylelint/presets/css-modules.js

@@ -0,0 +1,43 @@
+/**
+ * CSS Modules Stylelint preset
+ *
+ * Configuration for projects using CSS Modules.
+ * Allows CSS Modules-specific pseudo-classes and conventions.
+ *
+ * Key principles:
+ * - Support :global() and :local() pseudo-classes
+ * - Allow composition with composes
+ * - Support @value imports
+ * - Work alongside regular CSS/SCSS
+ */
+
+export default {
+  rules: {
+    // Allow CSS Modules pseudo-classes
+    'selector-pseudo-class-no-unknown': [
+      true,
+      {
+        ignorePseudoClasses: ['global', 'local', 'export', 'import']
+      }
+    ],
+
+    // Allow @value (CSS Modules constants)
+    'at-rule-no-unknown': [
+      true,
+      {
+        ignoreAtRules: ['value']
+      }
+    ],
+
+    // Allow 'composes' property (CSS Modules composition)
+    'property-no-unknown': [
+      true,
+      {
+        ignoreProperties: ['composes', 'compose-with']
+      }
+    ],
+
+    // CSS Modules often use camelCase
+    'selector-class-pattern': null // Disable pattern check for modules
+  }
+}