@polariens/kitsune-lint 1.0.0-rc.10

package/README.md

@@ -0,0 +1,268 @@
+# @polariens/kitsune-lint 🦊
+
+Opinionated ESLint & Prettier configs for high-quality Vue, TypeScript & Vitest projects.
+
+> **Kitsune** (狐) é a raposa mística do folclore japonês — astuta, adaptável e capaz de se transformar conforme o contexto. Assim como a kitsune, este pacote se molda ao seu projeto: você escolhe os módulos e as opções, e ele compõe as regras certas para cada cenário. Código limpo com a precisão de uma raposa.
+
+## O que é
+
+Um pacote instalável que padroniza regras de linting e formatação entre múltiplos projetos. As configurações são **modulares** — cada conjunto de regras (TypeScript, Vue, Pinia, segurança, etc.) é independente e configurável via opções.
+
+## Como usar
+
+### Instalação
+
+Primeiro, instale o pacote principal em seu projeto como dependência de desenvolvimento:
+
+```bash
+npm install --save-dev @polariens/kitsune-lint
+```
+
+As _peer dependencies_ correspondentes devem ser instaladas no projeto consumidor. Veja abaixo as opções de instalação dependendo do seu cenário.
+
+#### Instalação Completa (Todos os módulos)
+
+Se você planeja utilizar a configuração máxima com todos os módulos ativados no seu ecossistema (`security`, `cleanCode`, `pinia`, `vitest`, `typescript` e `vue`), execute este comando para instalar todas as ferramentas de uma vez:
+
+```bash
+npm install --save-dev eslint @eslint/js typescript-eslint globals eslint-plugin-security eslint-plugin-vue vue-eslint-parser eslint-plugin-pinia @vitest/eslint-plugin
+```
+
+#### Instalação Específica (Por módulo)
+
+Se preferir incluir apenas as peças que for usar, você deve sempre iniciar instalando as **Dependências Base**, que são essenciais para os módulos principais (que já vêm ativos por padrão, como `base`, `cleanCode` e `typescript`):
+
+```bash
+npm install --save-dev eslint @eslint/js typescript-eslint globals
+```
+
+Em seguida, instale os complementos exclusivos para cada módulo extra que for habilitar em seu `createKitsuneConfig()`:
+
+**Módulo `security` (Habilitado por padrão)**
+Necessário para a suíte de regras focadas em prevenir vulnerabilidades de segurança e injeções de código:
+```bash
+npm install --save-dev eslint-plugin-security
+```
+
+**Módulo `vue`**
+Pacotes necessários para realizar o lint na sintaxe `<template>`, `script setup` e validar as regras do Vue 3:
+```bash
+npm install --save-dev eslint-plugin-vue vue-eslint-parser
+```
+> *(Exemplo prático de setup em um projeto para uso apenas dos essenciais e módulo Vue:)*
+> ```bash
+> npm install --save-dev eslint @eslint/js typescript-eslint globals eslint-plugin-vue vue-eslint-parser
+> ```
+
+**Módulo `pinia`**
+O verificador de store e regras recomendadas para o gerenciamento de estado via Pinia:
+```bash
+npm install --save-dev eslint-plugin-pinia
+```
+
+**Módulo `vitest`**
+Para linting focado em arquivos de teste especificados nativamente pelas boas práticas do Vitest:
+```bash
+npm install --save-dev @vitest/eslint-plugin
+```
+
+### ESLint — Factory function (recomendado)
+
+A forma mais simples. O `createKitsuneConfig` compõe os módulos selecionados:
+
+```javascript
+// eslint.config.js
+import { createKitsuneConfig } from '@polariens/kitsune-lint/eslint';
+
+export default await createKitsuneConfig({
+  vue: true,
+  pinia: true,
+  tests: true,
+  vitest: true,
+});
+```
+
+Por padrão, `base`, `typescript`, `security` e `cleanCode` já vêm habilitados. Passe `false` para desativar:
+
+```javascript
+export default await createKitsuneConfig({
+  security: false,
+  vue: true,
+});
+```
+
+### ESLint — Customizando módulos
+
+Cada módulo aceita um objeto de opções no lugar de `true`:
+
+```javascript
+export default await createKitsuneConfig({
+  base: { environment: 'node' },
+  cleanCode: { maxDepth: 3, maxParams: 3, complexity: 10, maxLines: 300 },
+  vue: { apiStyle: 'composition' },
+  pinia: true,
+  vitest: {
+    titlePattern: '^should .+',
+    titleMessage: 'Test title must start with "should"',
+    fn: 'it',
+    maxNestedDescribe: 2,
+  },
+});
+```
+
+### ESLint — Imports granulares
+
+Para controle total, importe cada módulo diretamente:
+
+```javascript
+// eslint.config.js
+import { base } from '@polariens/kitsune-lint/eslint/base';
+import { typescript } from '@polariens/kitsune-lint/eslint/typescript';
+import { vue } from '@polariens/kitsune-lint/eslint/vue';
+import { pinia } from '@polariens/kitsune-lint/eslint/pinia';
+
+export default [
+  ...base(),
+  ...typescript(),
+  ...vue(),
+  ...(await pinia()),
+];
+```
+
+### ESLint — Estendendo com configs extras
+
+Use `extend` para adicionar configs de plugins externos (ex: `eslint-config-prettier`):
+
+```javascript
+import { createKitsuneConfig } from '@polariens/kitsune-lint/eslint';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import pluginVue from 'eslint-plugin-vue';
+
+export default await createKitsuneConfig({
+  vue: true,
+  pinia: true,
+  tests: true,
+  vitest: true,
+  extend: [
+    ...pluginVue.configs['flat/recommended'],
+    eslintConfigPrettier,
+  ],
+});
+```
+
+### Prettier
+
+Uso direto da config padrão:
+
+```javascript
+// prettier.config.mjs
+import { prettierConfig } from '@polariens/kitsune-lint/prettier';
+export default prettierConfig;
+```
+
+Com overrides:
+
+```javascript
+import { createPrettierConfig } from '@polariens/kitsune-lint/prettier';
+export default createPrettierConfig({ printWidth: 120 });
+```
+
+## Módulos
+
+| Módulo       | Default | Descrição                                                    |
+| ------------ | ------- | ------------------------------------------------------------ |
+| `base`       | ✅ on   | Globals do ambiente (browser/node)                           |
+| `typescript` | ✅ on   | Regras TS recomendadas + naming conventions                  |
+| `security`   | ✅ on   | Prevenção de eval, XSS, injection + eslint-plugin-security   |
+| `cleanCode`  | ✅ on   | SRP, legibilidade, imutabilidade, organização                |
+| `vue`        | ❌ off  | Vue 3 + script setup + type-based props/emits                |
+| `pinia`      | ❌ off  | Stores Pinia — naming, organização, boas práticas            |
+| `tests`      | ❌ off  | Relaxamentos para arquivos de teste (desliga regras rígidas) |
+| `vitest`     | ❌ off  | Regras do plugin Vitest (naming, hooks, describe)            |
+
+## Opções dos módulos
+
+### base
+
+| Opção         | Padrão      | Descrição                                        |
+| ------------- | ----------- | ------------------------------------------------ |
+| `environment` | `'browser'` | Globals: `browser`, `node`, `shared-node-browser`|
+
+### typescript
+
+| Opção    | Padrão         | Descrição          |
+| -------- | -------------- | ------------------ |
+| `ignores`| configs + dist | Patterns a ignorar |
+| `rules`  | `{}`           | Regras extras      |
+
+### security
+
+| Opção           | Padrão | Descrição                     |
+| --------------- | ------ | ----------------------------- |
+| `pluginEnabled` | `true` | Usar `eslint-plugin-security` |
+| `rules`         | `{}`   | Regras extras                 |
+
+### cleanCode
+
+| Opção                 | Padrão | Descrição                          |
+| --------------------- | ------ | ---------------------------------- |
+| `maxDepth`            | `4`    | Profundidade máxima de aninhamento |
+| `maxParams`           | `4`    | Parâmetros máximos por função      |
+| `complexity`          | `14`   | Complexidade ciclomática máxima    |
+| `maxLines`            | `400`  | Linhas máximas por arquivo         |
+| `maxLinesPerFunction` | `80`   | Linhas máximas por função          |
+| `rules`               | `{}`   | Regras extras                      |
+
+### vue
+
+| Opção      | Padrão           | Descrição           |
+| ---------- | ---------------- | ------------------- |
+| `apiStyle` | `'script-setup'` | Estilo de API Vue   |
+| `rules`    | `{}`             | Regras extras       |
+
+### pinia
+
+| Opção   | Padrão                    | Descrição                       |
+| ------- | ------------------------- | ------------------------------- |
+| `files` | `['src/state/**/*.ts']`   | Override dos file patterns      |
+| `rules` | `{}`                      | Regras extras                   |
+
+### tests
+
+Relaxamentos para arquivos de teste — desliga regras rígidas de produção como `complexity`, `max-lines`, `max-lines-per-function`, `no-explicit-any`, `naming-convention`, etc.
+
+| Opção   | Padrão                          | Descrição                  |
+| ------- | ------------------------------- | -------------------------- |
+| `files` | `['tests/**/*.{js,mjs,cjs,ts}']`| Override dos file patterns |
+| `rules` | `{}`                            | Regras extras              |
+
+### vitest
+
+| Opção              | Padrão         | Descrição                        |
+| ------------------ | -------------- | -------------------------------- |
+| `fn`               | `'test'`       | `test()` ou `it()`              |
+| `titlePattern`     | Gherkin PT-BR  | Regex do título dos testes       |
+| `titleMessage`     | mensagem PT-BR | Mensagem de erro                 |
+| `maxNestedDescribe`| `3`            | Máximo de describe aninhados     |
+| `rules`            | `{}`           | Regras extras                    |
+
+## Estrutura
+
+```
+@polariens/kitsune-lint/
+├── package.json
+├── eslint/
+│   ├── index.mjs            # Factory createKitsuneConfig + re-exports
+│   ├── utils.mjs             # Patterns de arquivos compartilhados
+│   └── configs/
+│       ├── base.mjs          # Globals do ambiente (browser/node)
+│       ├── typescript.mjs    # Regras TypeScript + naming conventions
+│       ├── security.mjs      # Prevenção de eval, XSS, injection
+│       ├── clean-code.mjs    # SRP, legibilidade, imutabilidade
+│       ├── vue.mjs           # Vue 3 + script setup
+│       ├── pinia.mjs         # Stores Pinia
+│       ├── tests.mjs         # Relaxamentos para testes
+│       └── vitest.mjs        # Regras plugin Vitest
+└── prettier/
+    └── index.mjs             # Config Prettier exportável
+```

package/bin/copy-prettierignore.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const source = resolve(__dirname, '..', 'prettier', '.prettierignore');
+const dest = resolve(process.cwd(), '.prettierignore');
+
+const force = process.argv.includes('--force');
+
+if (existsSync(dest) && !force) {
+  const existing = readFileSync(dest, 'utf-8');
+  const template = readFileSync(source, 'utf-8');
+
+  if (existing === template) {
+    console.info('[lint-config] .prettierignore já está atualizado.');
+    process.exit(0);
+  }
+
+  console.error(
+    '[lint-config] .prettierignore já existe e difere do template.\n' +
+      '  Use --force para sobrescrever.'
+  );
+  process.exit(1);
+}
+
+cpSync(source, dest);
+console.info(`[lint-config] .prettierignore copiado para ${dest}`);

package/eslint/configs/base.d.mts

@@ -0,0 +1,10 @@
+import type { Linter } from 'eslint';
+
+export interface BaseOptions {
+  /** File patterns override */
+  files?: string[];
+  /** Ambiente de globals a aplicar @default 'browser' */
+  environment?: 'browser' | 'node' | 'shared-node-browser' | 'worker' | 'serviceworker';
+}
+
+export declare function base(options?: BaseOptions): Linter.Config[];

package/eslint/configs/base.mjs

@@ -0,0 +1,28 @@
+import globals from 'globals';
+
+import { resolveFiles } from '../utils.mjs';
+
+/**
+ * @typedef {Object} BaseOptions
+ * @property {string[]} [files] - File patterns override
+ * @property {'browser' | 'node' | 'shared-node-browser'} [environment='browser'] - Ambiente global
+ */
+
+/**
+ * Configuração base com globals do ambiente.
+ * @param {BaseOptions} [options={}]
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function base(options = {}) {
+  const { files, environment = 'browser' } = options;
+
+  return [
+    {
+      files: resolveFiles('all', files),
+      name: '@kitsune/base/globals',
+      languageOptions: {
+        globals: globals[environment],
+      },
+    },
+  ];
+}

package/eslint/configs/clean-code.d.mts

@@ -0,0 +1,20 @@
+import type { Linter } from 'eslint';
+
+export interface CleanCodeOptions {
+  /** File patterns override */
+  files?: string[];
+  /** Profundidade máxima de aninhamento @default 4 */
+  maxDepth?: number;
+  /** Número máximo de parâmetros por função @default 4 */
+  maxParams?: number;
+  /** Complexidade ciclomática máxima @default 14 */
+  complexity?: number;
+  /** Linhas máximas por arquivo @default 400 */
+  maxLines?: number;
+  /** Linhas máximas por função @default 80 */
+  maxLinesPerFunction?: number;
+  /** Regras adicionais ou overrides */
+  rules?: Partial<Linter.RulesRecord>;
+}
+
+export declare function cleanCode(options?: CleanCodeOptions): Linter.Config[];

package/eslint/configs/clean-code.mjs

@@ -0,0 +1,102 @@
+import { resolveFiles } from '../utils.mjs';
+
+/**
+ * @typedef {Object} CleanCodeOptions
+ * @property {string[]} [files] - File patterns override
+ * @property {number} [maxDepth=4] - Profundidade máxima de aninhamento
+ * @property {number} [maxParams=4] - Número máximo de parâmetros
+ * @property {number} [complexity=14] - Complexidade ciclomática máxima
+ * @property {number} [maxLines=400] - Linhas máximas por arquivo
+ * @property {number} [maxLinesPerFunction=80] - Linhas máximas por função
+ * @property {Record<string, unknown>} [rules] - Regras adicionais ou overrides
+ */
+
+/**
+ * Regras de clean code para legibilidade e manutenibilidade.
+ * @param {CleanCodeOptions} [options={}]
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function cleanCode(options = {}) {
+  const {
+    files,
+    maxDepth = 4,
+    maxParams = 4,
+    complexity: maxComplexity = 14,
+    maxLines = 400,
+    maxLinesPerFunction = 80,
+    rules: extraRules = {},
+  } = options;
+
+  const resolvedFiles = resolveFiles('all', files);
+
+  return [
+    {
+      files: resolvedFiles,
+      name: '@kitsune/clean-code/rules',
+      rules: {
+        // --- Single Responsibility (SRP) ---
+        complexity: ['warn', maxComplexity],
+        'max-lines': ['warn', { max: maxLines, skipBlankLines: true, skipComments: true }],
+        'max-lines-per-function': ['warn', { max: maxLinesPerFunction, skipBlankLines: true, skipComments: true }],
+        'max-depth': ['error', maxDepth],
+        'max-params': ['error', maxParams],
+
+        // --- Readability & Expressiveness ---
+        'no-negated-condition': 'error',
+        'no-nested-ternary': 'error',
+        'no-unneeded-ternary': 'error',
+        'no-else-return': 'error',
+        'no-lonely-if': 'error',
+        'prefer-template': 'error',
+        'object-shorthand': 'error',
+        curly: ['error', 'all'],
+        'arrow-body-style': ['error', 'as-needed'],
+        'no-multi-assign': 'error',
+        'no-unreachable-loop': 'error',
+        'no-unused-labels': 'error',
+
+        // --- Immutability & Safety ---
+        'no-param-reassign': ['error', { props: false }],
+        'no-return-assign': ['error', 'always'],
+        'no-sequences': 'error',
+        'no-constructor-return': 'error',
+        'no-promise-executor-return': 'error',
+        // Evita modificação de built-ins
+        'no-extend-native': 'error',
+
+        // --- Code Organization ---
+        'default-case-last': 'error',
+        'grouped-accessor-pairs': ['error', 'getBeforeSet'],
+        'max-statements': ['error', 20],
+
+        // --- Bug Prevention ---
+        'no-template-curly-in-string': 'warn',
+        'no-useless-return': 'error',
+
+        ...extraRules,
+      },
+    },
+    {
+      /**
+       * Regra personalizada para composables e stores pinia que por padrão podem ter mais linhas
+       * devido aos exports e variáveis de estado ref/computed.
+       * Padrão de arquivos: iniciando com `use`
+       */
+      files: resolvedFiles.map((pattern) => {
+        const parts = pattern.split('/');
+        const lastPart = parts[parts.length - 1];
+        if (lastPart.includes('*')) {
+          parts[parts.length - 1] = lastPart.replace('*', 'use*');
+        }
+        return parts.join('/');
+      }),
+      name: '@kitsune/clean-code/use-rules',
+      rules: {
+        'max-lines-per-function': [
+          'warn',
+          { max: Math.max(200, maxLinesPerFunction), skipBlankLines: true, skipComments: true },
+        ],
+      },
+    },
+  ];
+}

package/eslint/configs/pinia.d.mts

@@ -0,0 +1,10 @@
+import type { Linter } from 'eslint';
+
+export interface PiniaOptions {
+  /** File patterns override @default ['src/state/**\/*.ts'] */
+  files?: string[];
+  /** Regras adicionais ou overrides */
+  rules?: Partial<Linter.RulesRecord>;
+}
+
+export declare function pinia(options?: PiniaOptions): Promise<Linter.Config[]>;

package/eslint/configs/pinia.mjs

@@ -0,0 +1,36 @@
+import { resolveFiles } from '../utils.mjs';
+
+/**
+ * @typedef {Object} PiniaOptions
+ * @property {string[]} [files] - File patterns override (default: src/state/**\/*.ts)
+ * @property {Record<string, unknown>} [rules] - Regras adicionais ou overrides
+ */
+
+/**
+ * Regras para stores Pinia — organização, naming e boas práticas.
+ * @param {PiniaOptions} [options={}]
+ * @returns {Promise<import('eslint').Linter.Config[]>}
+ */
+export async function pinia(options = {}) {
+  const { files, rules: extraRules = {} } = options;
+
+  const pluginPinia = await import('eslint-plugin-pinia').then((m) => m.default ?? m);
+
+  return [
+    {
+      files: resolveFiles('pinia', files),
+      name: '@kitsune/pinia/rules',
+      plugins: { pinia: pluginPinia },
+      rules: {
+        'pinia/never-export-initialized-store': 'error',
+        'pinia/no-duplicate-store-ids': 'error',
+        'pinia/no-return-global-properties': 'error',
+        'pinia/no-store-to-refs-in-store': 'error',
+        'pinia/prefer-single-store-per-file': 'warn',
+        'pinia/prefer-use-store-naming-convention': 'warn',
+        'pinia/require-setup-store-properties-export': 'warn',
+        ...extraRules,
+      },
+    },
+  ];
+}

package/eslint/configs/security.d.mts

@@ -0,0 +1,12 @@
+import type { Linter } from 'eslint';
+
+export interface SecurityOptions {
+  /** File patterns override */
+  files?: string[];
+  /** Habilitar eslint-plugin-security @default true */
+  pluginEnabled?: boolean;
+  /** Regras adicionais ou overrides */
+  rules?: Partial<Linter.RulesRecord>;
+}
+
+export declare function security(options?: SecurityOptions): Linter.Config[];

package/eslint/configs/security.mjs

@@ -0,0 +1,46 @@
+import pluginSecurity from 'eslint-plugin-security';
+
+import { resolveFiles } from '../utils.mjs';
+
+/**
+ * @typedef {Object} SecurityOptions
+ * @property {string[]} [files] - File patterns override
+ * @property {boolean} [pluginEnabled=true] - Habilitar eslint-plugin-security
+ * @property {Record<string, unknown>} [rules] - Regras adicionais ou overrides
+ */
+
+/**
+ * Regras de segurança para prevenir vulnerabilidades comuns.
+ * @param {SecurityOptions} [options={}]
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function security(options = {}) {
+  const { files, pluginEnabled = true, rules: extraRules = {} } = options;
+  const resolvedFiles = resolveFiles('all', files);
+
+  const configs = []
+
+  if (pluginEnabled) {
+    configs.push({
+      ...pluginSecurity.configs.recommended,
+      files: resolvedFiles,
+      name: '@kitsune/security/plugin',
+    });
+  }
+
+  configs.push({
+    files: resolvedFiles,
+    name: '@kitsune/security/rules',
+    rules: {
+      'no-alert': 'error',
+      'no-eval': 'error',
+      'no-debugger': 'error',
+      'no-new-func': 'error',
+      'no-script-url': 'error',
+      'no-implied-eval': 'error',
+      ...extraRules,
+    },
+  })
+
+  return configs;
+}

package/eslint/configs/tests.d.mts

@@ -0,0 +1,10 @@
+import type { Linter } from 'eslint';
+
+export interface TestsOptions {
+  /** File patterns override */
+  files?: string[];
+  /** Regras adicionais ou overrides */
+  rules?: Partial<Linter.RulesRecord>;
+}
+
+export declare function tests(options?: TestsOptions): Linter.Config[];

package/eslint/configs/tests.mjs

@@ -0,0 +1,40 @@
+import { resolveFiles } from '../utils.mjs';
+
+/**
+ * @typedef {Object} TestsOptions
+ * @property {string[]} [files] - File patterns override
+ * @property {Record<string, unknown>} [rules] - Regras adicionais ou overrides
+ */
+
+/**
+ * Relaxamentos para arquivos de teste — desliga regras rígidas de produção
+ * que atrapalham a escrita de testes (complexity, max-lines, naming, etc).
+ * @param {TestsOptions} [options={}]
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function tests(options = {}) {
+  const { files, rules: extraRules = {} } = options;
+
+  return [
+    {
+      files: resolveFiles('tests', files),
+      name: '@kitsune/tests/relaxations',
+      rules: {
+        'max-lines-per-function': 'off',
+        'max-lines': 'off',
+        complexity: 'off',
+        '@typescript-eslint/no-shadow': 'off',
+        '@typescript-eslint/no-non-null-assertion': 'off',
+        '@typescript-eslint/no-explicit-any': 'off',
+        '@typescript-eslint/naming-convention': 'off',
+        'no-promise-executor-return': 'off',
+        'no-param-reassign': 'off',
+        'no-constructor-return': 'off',
+        'no-script-url': 'off',
+        'security/detect-object-injection': 'off',
+        'security/detect-unsafe-regex': 'off',
+        ...extraRules,
+      },
+    },
+  ];
+}

package/eslint/configs/typescript.d.mts

@@ -0,0 +1,14 @@
+import type { Linter } from 'eslint';
+
+export interface TypescriptOptions {
+  /** File patterns override */
+  files?: string[];
+  /** Patterns a ignorar */
+  ignores?: string[];
+  /** Patterns a ignorar substituindo qualquer padrão do pacote */
+  replaceIgnores?: string[];
+  /** Regras adicionais ou overrides */
+  rules?: Partial<Linter.RulesRecord>;
+}
+
+export declare function typescript(options?: TypescriptOptions): Linter.Config[];