@regcheq/standards

Paquete interno que centraliza los estándares de calidad de código para todos los proyectos de Regcheq. Elimina la duplicación de configuración de ESLint+SonarJS, Prettier, Commitlint, Husky y validación de ramas — cada proyecto extiende este paquete en lugar de copiar y mantener su propio setup.

Versiones y compatibilidad

Versiones mínimas requeridas (peerDependencies)

| Dependencia | Versión mínima | Notas | |---|---|---| | eslint | >=9.0.0 | Ver nota ESLint 9 + legacy config abajo | | @typescript-eslint/eslint-plugin | >=8.0.0 | | | @typescript-eslint/parser | >=8.0.0 | | | typescript-eslint | >=8.0.0 | Solo flat config | | @eslint/js | >=9.0.0 | Solo flat config | | eslint-plugin-sonarjs | >=1.0.0 | Reglas verificadas compatibles hasta v4 | | eslint-config-prettier | >=9.0.0 | | | globals | >=14.0.0 | Solo flat config | | prettier | >=3.0.0 | Solo si usás @regcheq/standards/prettier |

Dependencias requeridas por preset

| Preset | Dependencias adicionales requeridas | Restricción especial | |---|---|---| | eslint (flat config) | typescript-eslint @eslint/js globals eslint-config-prettier eslint-plugin-sonarjs | Requiere eslint >= 9 y tsconfig.eslint.json | | eslint/nestjs | @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-prettier eslint-plugin-sonarjs | — | | eslint/lambda | @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-prettier eslint-plugin-sonarjs | — | | eslint/express | @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-prettier eslint-plugin-sonarjs | — | | eslint/loopback | @loopback/eslint-config @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-plugin-sonarjs | ESLint 8 obligatorio — ver nota abajo | | eslint/react | @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-sonarjs | — | | eslint/vue | @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-plugin-vue vue-eslint-parser eslint-plugin-sonarjs | — |

LoopBack — reglas externas del framework

El preset eslint/loopback extiende @loopback/eslint-config, que es la configuración ESLint oficial mantenida por el equipo de LoopBack. Eso significa que las reglas de lint base (TypeScript, mocha, etc.) las define LoopBack, y este preset suma encima las 23+ reglas SonarJS de Regcheq.

Restricción actual: @loopback/eslint-config v15 requiere eslint: "^8.57.1". Los repos LoopBack deben quedarse en ESLint 8 hasta que LoopBack publique soporte para ESLint 9.

# LoopBack repos: instalar con ESLint 8
npm i -D eslint@^8.57.1 @loopback/eslint-config eslint-plugin-sonarjs

Para saber cuándo LoopBack soporte ESLint 9: revisar releases de @loopback/eslint-config.

Lo mismo aplica si en el futuro otros frameworks (NestJS, etc.) proveen su propio eslint-config con versiones pinneadas — siempre hay que verificar la compatibilidad de ESLint antes de actualizar.

ESLint 9 + repos con .eslintrc.js (legacy config)

Los presets nestjs, lambda, express, react, vue generan un .eslintrc.js en el repo consumidor. ESLint 9 cambia el formato por defecto a flat config (eslint.config.mjs), pero sigue soportando el formato legacy. Para que funcione con ESLint 9 sin migrar a flat config, agregar la variable de entorno en el script lint:

// package.json del repo consumidor
{
  "scripts": {
    "lint": "ESLINT_USE_FLAT_CONFIG=false eslint \"{src,apps,libs,test}/**/*.ts\""
  }
}

El camino final es migrar a eslint.config.mjs usando el preset flat config (@regcheq/standards/eslint), pero ESLINT_USE_FLAT_CONFIG=false permite usar ESLint 9 con el formato legacy mientras dure la transición.

Instalación

npm install --save-dev @regcheq/standards

El paquete está publicado en el GitLab Package Registry interno. Asegurate de tener .npmrc configurado (ver .npmrc.example).

Desarrollo local

nvm use   # Node 22
npm ci

Husky ejecuta antes de cada commit:

• pre-commit: npm run lint + npm run test
• commit-msg: commitlint con los 13 tipos Regcheq
• pre-push: validación de nombre de rama

Presets ESLint

Seleccionar el preset según el framework

| Framework | Archivo de config en tu proyecto | Preset | |---|---|---| | Lambda / Node | .eslintrc.js | @regcheq/standards/eslint/lambda | | NestJS | .eslintrc.js | @regcheq/standards/eslint/nestjs | | LoopBack 4 | .eslintrc.js | @regcheq/standards/eslint/loopback | | Express | .eslintrc.js | @regcheq/standards/eslint/express | | React | .eslintrc.js | @regcheq/standards/eslint/react | | Vue 2 | .eslintrc.js | @regcheq/standards/eslint/vue | | ESLint 9 / flat config | eslint.config.mjs | @regcheq/standards/eslint |

Ver tabla completa de dependencias por preset en Versiones y compatibilidad.

Lambda / Node.js

// .eslintrc.js
module.exports = {
  extends: ['@regcheq/standards/eslint/lambda'],
};

Incluye TypeScript strict + SonarJS 23 reglas. Ignora .aws-sam/** y .serverless/**. Relaja reglas en archivos de test.

NestJS

// .eslintrc.js
module.exports = {
  extends: ['@regcheq/standards/eslint/nestjs'],
};

Agrega @typescript-eslint/recommended-requiring-type-checking. Desactiva explicit-function-return-type y no-explicit-any (NestJS usa decoradores).

LoopBack 4

// .eslintrc.js
module.exports = {
  extends: ['@regcheq/standards/eslint/loopback'],
};

Extiende @loopback/eslint-config (las reglas base las provee LoopBack) y suma las 23+ reglas SonarJS de Regcheq encima.

⚠️ Requiere ESLint 8. @loopback/eslint-config v15 no soporta ESLint 9. Ver nota completa.

Express

// .eslintrc.js
module.exports = {
  extends: ['@regcheq/standards/eslint/express'],
};

TypeScript + SonarJS para APIs Express sin framework de decoradores.

React

// .eslintrc.js
module.exports = {
  extends: ['@regcheq/standards/eslint/react'],
};

Agrega plugin:react/recommended + plugin:react-hooks/recommended. react/react-in-jsx-scope desactivado (React 17+).

Vue 2

// .eslintrc.js
module.exports = {
  extends: ['@regcheq/standards/eslint/vue'],
};

Usa vue-eslint-parser con plugin:vue/recommended.

ESLint 9 flat config (proyectos modernos)

// eslint.config.mjs
import regcheqEslint from '@regcheq/standards/eslint';

export default regcheqEslint({ type: 'ts' });

Opciones:

regcheqEslint({
  type: 'ts',                           // 'ts' (Node/Lambda) | 'react' (browser + TSX)
  tsconfigPath: './tsconfig.eslint.json',
  extraIgnores: ['generated/**'],
  extraRules: { 'no-console': 'error' },
});

Prettier

// prettier.config.js  o  .prettierrc.js
module.exports = require('@regcheq/standards/prettier');

O en package.json:

{
  "prettier": "@regcheq/standards/prettier"
}

Config aplicada:

{ semi: true, singleQuote: true, tabWidth: 2, trailingComma: 'all',
  printWidth: 100, bracketSpacing: true, arrowParens: 'avoid', endOfLine: 'auto' }

Commitlint

// commitlint.config.cjs
module.exports = require('@regcheq/standards/commitlint');

13 tipos de commit permitidos

| Tipo | Descripcion | Ejemplo | |---|---|---| | feat | Nueva funcionalidad | feat: agrega endpoint GET /contratos/count | | fix | Correccion de bug | fix: corrige validacion de DNI | | docs | Documentacion | docs: actualiza README | | style | Formato, sin logica | style: aplica prettier en controllers | | refactor | Refactoring | refactor: extrae logica a service | | test | Tests | test: agrega cobertura en handler | | chore | Mantenimiento | chore: actualiza dependencias | | ci | CI/CD | ci: corrige DEPLOY_NAME | | perf | Rendimiento | perf: configura keepAlive | | build | Sistema de build | build: migra a SAM | | release | Preparacion de release | release: bump version a 2.1.0 | | hotfix | Fix urgente en produccion | hotfix: revierte auth JWT | | revert | Revertir commit | revert: revierte feat de carga masiva |

Husky

Setup automatico

// Ejecutar una sola vez en el proyecto:
node -e "require('@regcheq/standards/husky').setup()"

Crea .husky/commit-msg, .husky/pre-commit, .husky/pre-push.

Setup manual

npx husky init

# commit-msg
cat > .husky/commit-msg << 'EOF'
#!/bin/sh
if head -n1 "$1" | grep -qE '^chore\(release\):'; then exit 0; fi
npx --no-install commitlint --edit "$1"
EOF

# pre-commit
echo 'npm run lint && npm run test' > .husky/pre-commit

# pre-push: validacion de rama
cp node_modules/@regcheq/standards/scripts/validate-branch.sh .husky/pre-push
chmod +x .husky/pre-push .husky/commit-msg .husky/pre-commit

package.json del proyecto:

{ "scripts": { "prepare": "husky" } }

Validacion de ramas

Prefijos validos

| Prefijo | Ejemplo | |---|---| | feat/ o feature/ | feat/REGCHEQ-123-agregar-dashboard | | fix/ o bugfix/ | fix/REGCHEQ-456-jwt-expiracion | | hotfix/ | hotfix/jwt-secret-leak | | release/ | release/2.1.0 | | chore/ | chore/actualizar-dependencias-q1 | | docs/ | docs/agregar-spec-api | | refactor/ | refactor/extraer-http-client | | test/ | test/agregar-cobertura-contratos | | ci/ | ci/corregir-deploy-name | | perf/ | perf/optimizar-queries | | build/ | build/migrar-a-sam |

Ramas exentas (no requieren prefijo): main, master, alpha, qa, beta, gamma, develop

Uso directo

node node_modules/@regcheq/standards/branch-validation/index.js

const { validateBranch } = require('@regcheq/standards/branch-validation');
const { valid } = validateBranch('feat/my-feature'); // true

Proyectos Python

Para proyectos Python sin Node como entorno:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
        args: [feat, fix, docs, style, refactor, test, chore, ci, perf, build, release, hotfix, revert]
  - repo: local
    hooks:
      - id: validate-branch-name
        name: Validate branch name
        entry: scripts/validate-branch.sh
        language: script
        stages: [pre-push]
        always_run: true

Contribuir a este repositorio

Branches

Formato: <tipo>/<descripcion> — la descripcion puede ser el nombre de la tarea, el ID de ClickUp, o ambos.

feature/implement-eslint-base
feature/86e02fyaq
feature/86e02fyaq-implement-eslint-base
feat/ST-02-sonarjs-rules
fix/branch-validation-regex
hotfix/broken-loopback-preset
release/1.1.0
chore/update-typescript-eslint

Tipos validos para branches: feature/ feat/ fix/ bugfix/ hotfix/ release/ chore/ docs/ refactor/ test/ ci/ perf/ build/

Ramas exentas (no requieren prefijo): master, develop

Commits (Conventional Commits)

Formato: <tipo>: <descripcion en presente, minusculas, sin punto final>

feat: agrega preset ESLint para NestJS
fix: corrige regex de validacion de ramas con tickets en mayusculas
docs: agrega ejemplos de uso en README
chore: actualiza typescript-eslint a v8
test: agrega tests para preset Vue 2
ci: configura cobertura en pipeline de GitLab
refactor: extrae reglas SonarJS a constante compartida

El mensaje no puede superar 100 caracteres. El tipo debe ser uno de los 13 definidos en commitlint/index.js.

Flujo de trabajo

1. Crear rama desde master: git checkout -b feature/mi-tarea
2. Implementar cambios
3. Correr: npm run lint && npm run test
4. Commit con tipo correcto: git commit -m "feat: ..."
5. Push y crear MR hacia master

Release automatico

Al hacer merge a master, semantic-release:

1. Analiza los commits desde el ultimo tag
2. Determina la siguiente version (SemVer basado en el tipo de commit)
3. Publica en GitLab Package Registry
4. Crea tag de version y actualiza CHANGELOG.md

| Tipo de commit | Bump de version | |---|---| | fix, perf, refactor, docs | PATCH (1.0.x) | | feat | MINOR (1.x.0) | | feat! o BREAKING CHANGE en el cuerpo | MAJOR (x.0.0) | | chore, ci, test, build | Sin release |

Versioning (SemVer)

• PATCH: ajustes de reglas sin cambio de API
• MINOR: nuevos presets o reglas opcionales
• MAJOR: cambios que rompen configuraciones existentes