@zairakai/js-dev-tools 1.0.0

package/README.md

@@ -0,0 +1,206 @@
+# @zairakai/js-dev-tools
+
+[![Main][pipeline-main-badge]][pipeline-main-link]
+[![Develop][pipeline-develop-badge]][pipeline-develop-link]
+
+[![npm][npm-badge]][npm-link]
+[![GitLab Release][gitlab-release-badge]][gitlab-release]
+[![License][license-badge]][license]
+
+[![Node.js][node-badge]][node]
+[![ESLint][eslint-badge]][eslint]
+[![Prettier][prettier-badge]][prettier]
+[![Stylelint][stylelint-badge]][stylelint]
+
+One unified toolkit to set up JavaScript/TypeScript quality tooling. Context-aware by default — it adapts to both standalone packages and full-stack applications.
+
+---
+
+## Why @zairakai/js-dev-tools?
+
+| Concept | Benefit |
+| :--- | :--- |
+| **Unified Logic** | The same quality gate for all your projects. Only the target (package or app) changes, not the rigor. |
+| **Concentrated Configs** | Centralized, opinionated configurations for all your tools. Avoid configuration drift across projects. |
+| **Unified Workflow** | One set of `make` commands to rule them all. Whether it's a small library or a large application, the quality gate remains the same. |
+| **Auto-Syncing CI** | Automatically updates GitLab CI ref tags in your `.gitlab-ci.yml` when you update the package. Keep your pipelines current without manual effort. |
+| **Zero Friction** | Automated setup script handles the heavy lifting on install. |
+
+---
+
+## Features
+
+| Tool | Responsibility |
+| :--- | :--- |
+| **ESLint** | Flat config with TypeScript, Vue 3, and import rules. |
+| **Prettier** | Opinionated formatter with SCSS and Tailwind support. |
+| **Stylelint** | SCSS linting with modern property ordering. |
+| **Markdownlint** | Consistent Markdown across all documentation. |
+| **Vitest** | Unit testing with v8 coverage. |
+| **Knip** | Dead code and unused dependency detection. |
+| **TypeScript** | Shared `tsconfig.base.json` for strict mode builds. |
+| **GitLab CI** | Reusable pipeline templates for npm packages and Laravel full-stack. |
+| **Git Hooks** | Automated quality checks and ticket prefixing. |
+| **Makefile** | Unified `make quality`, `make test`, `make ci` targets (delegated to core). |
+| **Shell Scripts** | Automated setup and config publishing. |
+
+On install, the `postinstall` script:
+
+- creates `Makefile` if missing (delegating to `node_modules/@zairakai/js-dev-tools/tools/make/core.mk`)
+- creates `.editorconfig`
+- creates `config/dev-tools/eslint.config.js` baseline
+- reports optional packages not yet installed
+
+---
+
+## Install
+
+```bash
+npm install --save-dev @zairakai/js-dev-tools
+```
+
+For Laravel full-stack projects, pair with `zairakai/laravel-dev-tools`:
+
+```bash
+composer require --dev zairakai/laravel-dev-tools
+npm install --save-dev @zairakai/js-dev-tools
+php artisan dev-tools:publish --fullstack
+```
+
+---
+
+## Usage
+
+```bash
+make quality       # eslint + prettier + stylelint + knip + markdownlint + shellcheck
+make quality-fix   # auto-fix all fixable issues
+make test          # vitest
+make test-all      # vitest + bats
+make test-coverage # vitest with coverage report
+make typecheck     # tsc --noEmit
+make build         # tsup or tsc
+make ci            # full pipeline simulation
+make doctor        # environment diagnostics
+```
+
+---
+
+## Configuration
+
+Extend the shared configs in your project files:
+
+```js
+// eslint.config.js
+export { default } from '@zairakai/js-dev-tools/eslint'
+
+// prettier.config.js
+export { default } from '@zairakai/js-dev-tools/prettier'
+
+// stylelint.config.js
+export { default } from '@zairakai/js-dev-tools/stylelint'
+
+// vitest.config.js
+import baseConfig from '@zairakai/js-dev-tools/vitest'
+import { defineConfig } from 'vitest/config'
+export default defineConfig({ ...baseConfig, test: { ...baseConfig.test } })
+```
+
+```json
+// tsconfig.json
+{ "extends": "@zairakai/js-dev-tools/tsconfig" }
+```
+
+---
+
+## Publishing configs
+
+Publish individual config files to `config/dev-tools/` (never overwritten unless `--force`):
+
+```bash
+# All at once
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish
+
+# By group
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=quality
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=style
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=testing
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=hooks
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=gitlab-ci
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=typescript
+
+# Single files
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=eslint
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=prettier
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=stylelint
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=vitest
+bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=tsconfig
+```
+
+---
+
+## GitLab CI pipeline templates
+
+Include in your consumer project's `.gitlab-ci.yml`:
+
+```yaml
+# npm package pipeline
+include:
+  - project: 'zairakai/npm-packages/js-dev-tools'
+    ref: v1.0.0          # pin to a release tag for reproducible builds
+    file: '.gitlab/ci/pipeline-js-package.yml'
+
+variables:
+  CACHE_KEY: "my-package-v1"
+  NPM_PACKAGE_NAME: "@myorg/my-package"
+```
+
+Available templates:
+
+- `.gitlab/ci/pipeline-js-package.yml` — security → install → validate → quality → test → build → publish → release
+- `.gitlab/ci/pipeline-js-app.yml` — JS quality + test jobs for Laravel full-stack apps
+
+---
+
+## Development
+
+```bash
+make quality          # full quality check
+make test-all         # vitest + bats
+make bats             # shell script tests only
+make doctor           # environment diagnostics
+```
+
+---
+
+## Getting Help
+
+[![License][license-badge]][license]
+[![Security Policy][security-badge]][security]
+[![Issues][issues-badge]][issues]
+
+**Made with ❤️ by [Zairakai][ecosystem]**
+
+<!-- Reference Links -->
+[pipeline-main-badge]: https://gitlab.com/zairakai/npm-packages/js-dev-tools/badges/main/pipeline.svg?ignore_skipped=true&key_text=Main
+[pipeline-main-link]: https://gitlab.com/zairakai/npm-packages/js-dev-tools/-/commits/main
+[pipeline-develop-badge]: https://gitlab.com/zairakai/npm-packages/js-dev-tools/badges/develop/pipeline.svg?ignore_skipped=true&key_text=Develop
+[pipeline-develop-link]: https://gitlab.com/zairakai/npm-packages/js-dev-tools/-/commits/develop
+[npm-badge]: https://img.shields.io/npm/v/@zairakai/js-dev-tools
+[npm-link]: https://www.npmjs.com/package/@zairakai/js-dev-tools
+[gitlab-release-badge]: https://img.shields.io/gitlab/v/release/zairakai/npm-packages/js-dev-tools?logo=gitlab
+[gitlab-release]: https://gitlab.com/zairakai/npm-packages/js-dev-tools/-/releases
+[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[license]: ./LICENSE
+[security-badge]: https://img.shields.io/badge/security-scanned-green.svg
+[security]: ./SECURITY.md
+[issues-badge]: https://img.shields.io/gitlab/issues/open-raw/zairakai%2Fnpm-packages%2Fdev-tools?logo=gitlab&label=Issues
+[issues]: https://gitlab.com/zairakai/npm-packages/js-dev-tools/-/issues
+[node-badge]: https://img.shields.io/badge/node.js-%3E%3D22-green.svg?logo=node.js
+[node]: https://nodejs.org
+[eslint-badge]: https://img.shields.io/badge/code%20style-eslint-4B32C3.svg?logo=eslint
+[eslint]: https://eslint.org
+[prettier-badge]: https://img.shields.io/badge/formatter-prettier-F7B93E.svg?logo=prettier
+[prettier]: https://prettier.io
+[stylelint-badge]: https://img.shields.io/badge/css-stylelint-263238.svg?logo=stylelint
+[stylelint]: https://stylelint.io
+[ecosystem]: https://gitlab.com/zairakai

package/config/.markdownlint.json

@@ -0,0 +1,7 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD024": {
+    "siblings_only": true
+  }
+}

package/config/.markdownlintignore

@@ -0,0 +1,5 @@
+.cache/
+.git/
+.opencode/
+node_modules/
+*.min.md

package/config/.prettierignore

@@ -0,0 +1,11 @@
+build/
+coverage/
+dist/
+node_modules/
+public/
+vendor/
+*.lock
+*.md
+*.min.css
+*.min.js
+gl-*.json

package/config/.stylelintignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+build/
+coverage/
+vendor/
+public/
+*.min.css

package/config/eslint.config.js

@@ -0,0 +1,198 @@
+/**
+ * Default ESLint configuration for @zairakai projects.
+ */
+import { includeIgnoreFile } from '@eslint/compat'
+import pluginJs from '@eslint/js'
+import pluginTypeScript from '@typescript-eslint/eslint-plugin'
+import parserTypeScript from '@typescript-eslint/parser'
+import eslintConfigPrettier from 'eslint-config-prettier'
+import pluginVue from 'eslint-plugin-vue'
+import globals from 'globals'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+const gitignorePath = path.resolve(process.cwd(), '.gitignore')
+const gitignoreConfig = existsSync(gitignorePath) ? [includeIgnoreFile(gitignorePath)] : []
+
+export default [
+  ...gitignoreConfig,
+  // Base JavaScript rules
+  pluginJs.configs.recommended,
+
+  // Vue configurations
+  ...pluginVue.configs['flat/strongly-recommended'],
+
+  // Prettier integration (must be last)
+  eslintConfigPrettier,
+
+  // Base configuration for all files
+  {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.es2022,
+      },
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      // Yoda style enforcement (Zairakai convention)
+      yoda: [
+        'error',
+        'always',
+        {
+          exceptRange: true,
+          onlyEquality: false,
+        },
+      ],
+
+      // Code quality
+      'no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+      'no-unused-expressions': [
+        'error',
+        {
+          allowShortCircuit: true,
+          allowTernary: true,
+          allowTaggedTemplates: true,
+        },
+      ],
+      'no-console': [
+        'warn',
+        {
+          allow: ['warn', 'error', 'info', 'debug'],
+        },
+      ],
+      'no-debugger': 'error',
+
+      // Best practices
+      eqeqeq: [
+        'error',
+        'always',
+        {
+          null: 'ignore',
+        },
+      ],
+      curly: ['error', 'all'],
+      'prefer-const': 'error',
+      'no-var': 'error',
+      'object-shorthand': 'error',
+      'prefer-template': 'error',
+      'prefer-arrow-callback': 'error',
+
+      // Import rules
+      'sort-imports': [
+        'error',
+        {
+          ignoreDeclarationSort: true,
+          ignoreMemberSort: false,
+          memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single'],
+        },
+      ],
+
+      // Vue specific rules (relaxed for flexibility)
+      'vue/multi-word-component-names': 'off',
+      'vue/require-default-prop': 'off',
+      'vue/valid-template-root': 'off',
+      'vue/no-v-html': 'warn',
+      'vue/require-v-for-key': 'error',
+      'vue/no-unused-components': 'warn',
+      'vue/component-name-in-template-casing': ['error', 'PascalCase'],
+      'vue/attribute-hyphenation': ['error', 'always'],
+      'vue/v-on-event-hyphenation': ['error', 'always'],
+    },
+  },
+
+  // TypeScript specific configuration
+  {
+    files: ['**/*.ts', '**/*.tsx', '**/*.vue'],
+    languageOptions: {
+      parser: parserTypeScript,
+      parserOptions: {
+        project: './tsconfig.json',
+        extraFileExtensions: ['.vue'],
+      },
+    },
+    plugins: {
+      '@typescript-eslint': pluginTypeScript,
+    },
+    rules: {
+      // Disable JS rules that conflict with TS
+      'no-unused-vars': 'off',
+      'no-undef': 'off',
+
+      // Enable TS rules
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/prefer-nullish-coalescing': 'error',
+      '@typescript-eslint/prefer-optional-chain': 'error',
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+    },
+  },
+
+  // Test files configuration
+  {
+    files: ['**/*.test.{js,ts}', '**/*.spec.{js,ts}', '**/tests/**/*'],
+    languageOptions: {
+      globals: {
+        ...globals.jest,
+        ...globals.vitest,
+        describe: 'readonly',
+        it: 'readonly',
+        test: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+        vi: 'readonly',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      'no-console': 'off',
+    },
+  },
+
+  // Configuration files
+  {
+    files: ['**/*.config.{js,ts}', '**/.*rc.{js,ts}'],
+    rules: {
+      'no-console': 'off',
+      '@typescript-eslint/no-var-requires': 'off',
+    },
+  },
+
+  // Ignore patterns
+  {
+    ignores: [
+      'build/**',
+      'coverage/**',
+      'dist/**',
+      'node_modules/**',
+      'public/**',
+      'storybook-static/**',
+      '.nuxt/**',
+      '.output/**',
+      '**/*.min.js',
+    ],
+  },
+]

package/config/knip.config.js

@@ -0,0 +1,40 @@
+/**
+ * Knip configuration for @zairakai/js-dev-tools
+ *
+ * This package ships bundled configs for consumer projects.
+ * Many dependencies are referenced as strings (prettier plugins, stylelint configs)
+ * rather than ES imports — knip cannot trace those automatically.
+ */
+
+export default {
+  entry: ['config/**/*.js'],
+
+  // "Referenced optional peerDependencies" is informational — stylelint is intentionally optional
+  exclude: ['optionalPeerDependencies'],
+
+  ignoreDependencies: [
+    // Prettier plugins — referenced as strings in config/prettier.config.js
+    '@prettier/plugin-php',
+    'prettier-plugin-blade',
+    'prettier-plugin-organize-imports',
+
+    // Stylelint configs/plugins — referenced as strings in config/stylelint.config.js
+    'stylelint-config-html',
+    'stylelint-config-recommended-vue',
+    'stylelint-config-standard',
+    'stylelint-config-standard-scss',
+    'stylelint-order',
+    'stylelint-scss',
+
+    // Coverage provider — referenced as string in config/vitest.config.js (provider: 'v8')
+    '@vitest/coverage-v8',
+
+    // Optional peer dep bundled for consumers
+    'zod',
+
+    // Used in Makefiles/Scripts for normalization
+    'sort-package-json',
+  ],
+
+  ignoreBinaries: ['make'],
+}

package/config/prettier.config.js

@@ -0,0 +1,121 @@
+/**
+ * Default Prettier configuration for @zairakai projects.
+ */
+
+const config = {
+  // Core formatting
+  printWidth: 120,
+  tabWidth: 2,
+  useTabs: false,
+  semi: false,
+  singleQuote: true,
+  quoteProps: 'as-needed',
+  trailingComma: 'es5',
+  bracketSpacing: true,
+  bracketSameLine: false,
+  arrowParens: 'always',
+  endOfLine: 'lf',
+
+  // HTML & Vue specific
+  htmlWhitespaceSensitivity: 'css',
+  vueIndentScriptAndStyle: true,
+  singleAttributePerLine: false,
+
+  // JSX specific
+  jsxSingleQuote: true,
+
+  // Prose formatting
+  proseWrap: 'preserve',
+  embeddedLanguageFormatting: 'auto',
+
+  // Plugin configuration
+  plugins: ['prettier-plugin-blade', '@prettier/plugin-php', 'prettier-plugin-organize-imports'],
+
+  // File-specific overrides
+  overrides: [
+    // TypeScript/JavaScript files
+    {
+      files: ['*.ts', '*.tsx', '*.js', '*.jsx', '*.vue'],
+      options: {
+        semi: false,
+        singleQuote: true,
+        trailingComma: 'es5',
+      },
+    },
+
+    // Vue files
+    {
+      files: '*.vue',
+      options: {
+        vueIndentScriptAndStyle: true,
+        singleAttributePerLine: true,
+      },
+    },
+
+    // SCSS/CSS files
+    {
+      files: ['*.scss', '*.css'],
+      options: {
+        tabWidth: 2,
+        singleQuote: false,
+        trailingComma: 'es5',
+        semi: false,
+      },
+    },
+
+    // PHP/Blade files
+    {
+      files: ['*.blade.php'],
+      options: {
+        tabWidth: 4,
+        useTabs: false,
+        phpVersion: '8.3',
+        trailingCommaPHP: true,
+        semi: false,
+      },
+    },
+
+    // JSON files
+    {
+      files: ['*.json', '*.jsonc'],
+      options: {
+        tabWidth: 2,
+        trailingComma: 'none',
+        semi: false,
+      },
+    },
+
+    // YAML files
+    {
+      files: ['*.yml', '*.yaml'],
+      options: {
+        tabWidth: 2,
+        singleQuote: false,
+        bracketSpacing: false,
+        semi: false,
+      },
+    },
+
+    // Package.json files
+    {
+      files: 'package.json',
+      options: {
+        tabWidth: 2,
+        trailingComma: 'none',
+        semi: false,
+      },
+    },
+
+    // Configuration files
+    {
+      files: ['*.config.js', '*.config.ts', '.*rc.js', '.*rc.ts'],
+      options: {
+        tabWidth: 2,
+        singleQuote: true,
+        semi: false,
+      },
+    },
+  ],
+}
+
+export default config

package/config/stylelint.config.js

@@ -0,0 +1,56 @@
+/**
+ * Full Stylelint config for @zairakai projects
+ */
+
+export default {
+  extends: [
+    'stylelint-config-standard-scss', // Base SCSS rules
+    'stylelint-config-recommended-vue', // Vue SFC support
+    'stylelint-config-html', // HTML support
+  ],
+  plugins: ['stylelint-scss'],
+
+  overrides: [
+    // Vue files
+    {
+      files: ['*.vue', '**/*.vue'],
+      rules: {
+        'scss/at-rule-no-unknown': true,
+      },
+    },
+    // SCSS files
+    {
+      files: ['*.scss', '**/*.scss'],
+      rules: {
+        'scss/at-mixin-argumentless-call-parentheses': 'never',
+        'scss/dollar-variable-pattern': '^[_a-z0-9\\-]+$',
+        'scss/selector-no-redundant-nesting-selector': true,
+      },
+    },
+  ],
+
+  rules: {
+    // SCSS basics
+    'declaration-block-no-redundant-longhand-properties': true,
+    'length-zero-no-unit': true,
+
+    // SCSS operator & function rules
+    'scss/at-rule-no-unknown': true,
+    'scss/at-mixin-argumentless-call-parentheses': 'never',
+
+    // Naming conventions
+    'scss/dollar-variable-pattern': '^[_a-z0-9\\-]+$',
+    'scss/selector-no-redundant-nesting-selector': true,
+  },
+
+  ignoreFiles: [
+    'node_modules/**/*',
+    'dist/**/*',
+    'build/**/*',
+    'coverage/**/*',
+    'public/**/*',
+    '.nuxt/**/*',
+    '.output/**/*',
+    '**/*.min.css',
+  ],
+}

package/config/tsconfig.base.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true,
+    "ignoreDeprecations": "5.0"
+  }
+}