Linting

Descripción general de la solución de linting

Jutro proporciona configuraciones administradas y predefinidas para los linters ESLint y Stylelint. Estas configuraciones compartidas aplican estándares y calidad de código coherentes en todas las aplicaciones de Jutro. Incluyen reglas para el estilo del código, las prácticas recomendadas de creación de códigos y los patrones específicos de Jutro. Las configuraciones se mantienen en paquetes de Jutro y se pueden actualizar fácilmente sin cambiar los archivos de configuración de su aplicación.

Aspectos clave de la configuración de linting de Jutro

Administración central: Las configuraciones se mantienen en paquetes de Jutro, no en la aplicación de usted.
Actualizaciones automáticas: Recibirá actualizaciones de reglas sin cambiar sus archivos de configuración.
Personalización: Podrá invalidar reglas específicas según sea necesario para su aplicación.
Validación de estándares en la nube: Parte de la solución de linting son las reglas de validación para las API y los patrones de Jutro.

Cómo se proporcionan las configuraciones de linting

Las configuraciones se proporcionan a través de los paquetes específicos de linter. Contienen las reglas y los ajustes preestablecidos que se utilizan cuando usted ejecuta los linters en la aplicación.

Configuración de ESLint

Paquete: @jutro/eslint-config

Reglas de ESLint

Estilo del código (Airbnb) (airbnb): Reglas y prácticas recomendadas sobre el estilo del código base.
TypeScript (plugin:@typescript-eslint/recommended): Verificación de tipo y reglas de linting específicas de TypeScript.
React y ganchos de React (plugin:react-hooks/recommended): Reglas para componentes de React y uso de ganchos.
Accesibilidad (plugin:jsx-a11y/recommended): Prácticas recomendadas de accesibilidad para JSX.
JSON/JSON5 (plugin:jsonc/recommended-with-jsonc): Reglas de linting para archivos JSON y JSON5.
Reglas de la plataforma de Jutro: Reglas personalizadas específicas de Jutro para la aplicación de la internacionalización (i18n) y validación de propiedades.
Estándares de la nube (@jutro/eslint-config/cloud-standards): Reglas de validación para API y patrones de Jutro (advertencias de forma predeterminada). Consulte la sección sobre estándares de la nube para obtener más información sobre las reglas y las opciones de personalización.

Configuración de Stylelint

Paquete: @jutro/stylelint-config

Reglas de Stylelint

SCSS (stylelint-config-standard-scss): Reglas estándares de SCSS para linting.
Aplicación de tokens de diseño: Reglas para el uso coherente de tokens de diseño en todas las hojas de estilo.
Estándares de la nube (@jutro/stylelint-config/cloud-standards): Reglas de validación para patrones de diseño de Jutro (advertencias de forma predeterminada). Consulte la sección sobre estándares de la nube para obtener más información sobre las reglas y las opciones de personalización.

Cómo usar los linters

Archivos de configuración

Para usar la solución linting de Jutro, necesita dos archivos de configuración linters en la raíz del proyecto:

.eslintrc.js. Archivo de configuración que aplica las reglas de ESLint desde @jutro/eslint-config. Este archivo proporciona el conjunto de reglas base para su aplicación y se puede personalizar agregando o invalidando reglas individuales.
.stylelintrc. Archivo de configuración que aplica las reglas de Stylelint desde @jutro/stylelint-config. Este archivo proporciona el conjunto de reglas base de estilo para su aplicación y se puede personalizar agregando o invalidando reglas individuales.

Archivos opcionales para excluir directorios o archivos desde linting:

.eslintignore. Especifica qué archivos y directorios debe omitir ESLint durante el linting (por ejemplo, node_modules/, dist/ o archivos generados).
.stylelintignore. Especifica qué archivos y directorios debe omitir Stylelint durante el linting (por ejemplo, node_modules/, dist/ u hojas de estilo de proveedores).

Configuración de los linters

Instale las dependencias:

npm install --save-dev \
  @jutro/eslint-config \
  @jutro/stylelint-config \
  eslint \
  stylelint

Cree .eslintrc.js en la raíz del proyecto:

.eslintrc.js
module.exports = {
  extends: ['@jutro/eslint-config'],
};

Cree .stylelintrc en la raíz del proyecto:
.stylelintrc
```
{
  "extends": "@jutro/stylelint-config"
}
```

Agregue scripts de linting a package.json:

package.json
{
  "scripts": {
    "lint:js": "eslint './**/*.{js,jsx,ts,tsx,json}'",
    "lint:css": "stylelint '**/*.scss'",
    "lint": "npm run lint:js && npm run lint:css"
  }
}

Ejecute los linters:

npm run lint        # Run all linters
npm run lint:js     # Run ESLint only
npm run lint:css    # Run Stylelint only

Utilice los scripts creados para ejecutar los linters y comprobar si hay problemas en el código cuando trabaje en la aplicación de Jutro. También puede configurar linting para que se ejecute automáticamente tras la confirmación mediante herramientas como lint-staged.

Ejecución de linters con la CLI de Jutro

Ejecute todos los linters y formateadores en su aplicación de Jutro utilizando el comando validate:linters. Esto ejecuta ESLint, Stylelint y Prettier:

jutro validate:linters

Note: Si no tiene Prettier agregado como una dependencia, el comando validate:linters falla. En este caso, utilice el método de scripts npm de la sección Configuración de los linters.

Si Prettier está instalado, pero no se proporciona ninguna configuración personalizada, el comando se ejecuta con la configuración predeterminada de Prettier.

Para obtener más detalles sobre este comando y parámetros adicionales, consulte la documentación sobre el comando validate:linters.

Ejemplos de configuración

Configuración predeterminada

La configuración predeterminada recomendada utiliza todas las reglas de ESLint y Stylelint con estándares de la nube como advertencias.

.eslintrc.js
module.exports = {
  extends: ['@jutro/eslint-config'],
};

::: nota

En el caso de ESlint, los ajustes preestablecidos @jutro/eslint-config y @jutro son intercambiables y proporcionan el mismo conjunto de reglas. La versión más corta @jutro es un alias conveniente para la configuración base de ESLint.

:::

.stylelintrc
{
  "extends": "@jutro/stylelint-config"
}

Estándares en la nube como errores

Trata las infracciones de los estándares de la nube como errores, en lugar de advertencias.

.eslintrc.js
module.exports = {
  extends: [
    '@jutro/eslint-config',
    '@jutro/eslint-config/cloud-standards-error',
  ],
};

.stylelintrc
{
  "extends": [
    "@jutro/stylelint-config",
    "@jutro/stylelint-config/cloud-standards-error"
  ]
}

Invalidaciones de reglas personalizadas

Desactive o modifique reglas específicas para su proyecto.

.eslintrc.js
module.exports = {
  extends: ['@jutro/eslint-config'],
  rules: {
    'no-console': 'warn', // Downgrade console warning from error to warning
    'react/prop-types': 'off', // Disable prop-types validation
    '@jutro/cloud-standards/no-internal-imports': 'off', // Disable internal imports check
  },
};

.stylelintrc
{
  "extends": "@jutro/stylelint-config",
  "rules": {
    "@jutro/cloud-standards/no-disallowed-css-vars": "off"
  }
}

Opciones de personalización

Hay dos niveles de personalización para las configuraciones de ESLint y Stylelint:

Nivel preestablecido: Elija qué ajuste preestablecido se extenderá (afecta la gravedad de los estándares de la nube):
- @jutro/eslint-config o @jutro/stylelint-config. Configuración predeterminada con problemas de estándares en la nube notificados como advertencias (opción predeterminada).
- @jutro/eslint-config/cloud-standards-error o @jutro/stylelint-config/cloud-standards-error. Problemas de estándares de la nube notificados como errores. Para mantener la configuración predeterminada para otras reglas, extienda primero la configuración base.
Nivel de regla: Invalide las reglas individuales en el objeto rules:
- Cambie la gravedad: 'no-console': 'warn' (error → advertencia)
- Deshabilite las reglas: 'no-console': 'off'
- Configure las opciones de la regla: 'max-params': ['warn', 2]

Cuando corresponda, intente seguir los estándares de Jutro o hacerlos coincidir lo más posible. Pero si quiere cambiarlos, agregue una matriz de reglas a su .eslintrc.js o .stylelintrc.

Para obtener más información sobre las reglas, consulte la documentación oficial de ESLint y Stylelint.

Consulte los ejemplos a continuación para obtener más detalles sobre las opciones de personalización.

Deshabilitación de una regla específica

ESLint:

.eslintrc.js
module.exports = {
  extends: ['@jutro/eslint-config'],
  rules: {
    '@jutro/cloud-standards/no-internal-imports': 'off',
  },
};

Stylelint:

.stylelintrc
{
  "extends": "@jutro/stylelint-config",
  "rules": {
    "@jutro/cloud-standards/no-disallowed-css-vars": "off"
  }
}

Cambio de la gravedad de la regla

ESLint:

.eslintrc.js
module.exports = {
  extends: ['@jutro/eslint-config'],
  rules: {
    'no-console': 'warn',
    'react/prop-types': 'error',
  },
};

Stylelint:

.stylelintrc
{
  "extends": "@jutro/stylelint-config",
  "rules": {
    "color-no-invalid-hex": "error",
    "indentation": "warn"
  }
}

Configuración de las opciones de la regla

Algunas reglas aceptan parámetros de configuración.

ESLint:

Por ejemplo, react/jsx-max-props-per-line (del plugin de React) limita la cantidad de propiedades por línea. Formato: ['severity', { option: value }].

.eslintrc.js
module.exports = {
  extends: ['@jutro/eslint-config'],
  rules: {
    'react/jsx-max-props-per-line': ['warn', { maximum: 3 }], // React plugin rule
    'max-lines': ['error', 300], // Core ESLint rule
  },
};

Stylelint:

Por ejemplo, indentation controla el espaciado. Formato: ['severity', numericValue] o ['severity', { option: value }].

.stylelintrc
{
  "extends": "@jutro/stylelint-config",
  "rules": {
    "indentation": ["error", 2],
    "max-nesting-depth": ["warn", 3]
  }
}

Validación de estándares de la nube

Los estándares de la nube son un conjunto de reglas para compilar aplicaciones de Jutro. Jutro introduce compatibilidad para validar estos estándares en configuraciones de linting, lo que permite a los desarrolladores asegurarse de que su código respete estas reglas.

Aspectos clave de la validación de los estándares de la nube:

Las reglas verifican solo las posibles infracciones de la API pública de Jutro y los patrones requeridos de Jutro. Consulte la sección Reglas de estándares de la nube para obtener más información.
Con las configuraciones predeterminadas de ESLint y Stylelint, los problemas se informan como advertencias, no como errores. Esto se puede modificar con ajustes preestablecidos o desactivando reglas individuales.

Reglas de estándares de la nube

Linter	Recorrido	Regla
ESLint	`@jutro/cloud-standards/no-restricted-design-tokens`	Los tokens de diseño personalizados definidos en los archivos `\*.json` no se pueden declarar en el espacio de nombre `jds`.
ESLint	`@jutro/cloud-standards/no-internal-imports`	El código de aplicación solo debe importarse desde el punto de entrada principal de los paquetes de Jutro (por ejemplo, `@jutro/components`), no desde rutas anidadas (por ejemplo, `@jutro/components/src`) ni desde directorios internos (por ejemplo, `@jutro/theme/internal`).
Stylelint	`@jutro/cloud-standards/no-disallowed-css-vars`	Las variables CSS internas para los tokens de diseño (que coincidan con --JDS-*-INTERNAL) no pueden utilizarse en las hojas de estilo.

Ajustes preestablecidos de estándares de la nube

Las configuraciones de estándares de la nube no entran en conflicto con otras reglas de linting. Los ajustes preestablecidos se pueden combinar con otras configuraciones sin generar conflictos. Cuando haga referencia a los ajustes preestablecidos de estándares de la nube en su configuración, utilice la ruta completa hasta los paquetes de configuración.

ESLint

@jutro/eslint-config/cloud-standards: Valida las reglas de los estándares de la nube con gravedad de advertencia. Habilitado de forma predeterminada en el ajuste preestablecido @jutro/eslint-config.
@jutro/eslint-config/cloud-standards-error: Valida las reglas de los estándares de la nube con gravedad de error.

Stylelint

@jutro/stylelint-config/cloud-standards: Valida las reglas de los estándares de la nube con gravedad de advertencia. Habilitado de forma predeterminada en el ajuste preestablecido @jutro/stylelint-config.
@jutro/stylelint-config/cloud-standards-error: Valida las reglas de los estándares de la nube con gravedad de error.

Requisitos

JS/TS de linting: Los paquetes de ESLint y @jutro/eslint-config se requieren como dependencias en package.json.
Hojas de estilo de linting: Los paquetes de Stylelint y @jutro/stylelint-config se requieren como dependencias en package.json.

Configuraciones de ejemplo

ESLint:

.eslintrc.js
const eslintDefault = {
  extends: [
    '@jutro', // base config with cloud standard warnings
  ],
};

.eslintrc.js
const eslintDefaultWithCloudStandardErrors = {
  extends: [
    '@jutro', // base config
    '@jutro/eslint-config/cloud-standards-error', // cloud standard errors
  ],
};

Stylelint:

.stylelintrc.js
const stylelintDefault = {
  extends: [
    '@jutro/stylelint-config', // base config with cloud standard warnings
  ],
};

.stylelintrc.js
const stylelintDefaultWithCloudStandardErrors = {
  extends: [
    '@jutro/stylelint-config', // base config
    '@jutro/stylelint-config/cloud-standards-error', // cloud standard errors
  ],
};

Deshabilitación de reglas individuales

Este no es el método recomendado, pero existe una opción para deshabilitar las reglas individuales para la validación de estándares de la nube.

.eslintrc.js
module.exports = {
  extends: ['@jutro'],
  rules: {
    /* Disable cloud standard rule */
    '@jutro/cloud-standards/no-internal-imports': 'off',
  },
};

Migración desde el paquete de herramientas de compilación

La importación de ajustes preestablecidos de ESLint y Stylelint desde el paquete @jutro/build-tools es la forma obsoleta de acceder a las configuraciones de linting de Jutro. Para migrar a la nueva configuración con paquetes específicos de linter con reglas de linting, debe hacer lo siguiente:

Agregue las siguientes importaciones a la sección devDependencies del archivo package.json:
- "@jutro/eslint-config": "10.13.1"
- "@jutro/stylelint-config": "10.13.1"
Actualice la configuración de los linters:

.eslintrc
.eslintrc antes	`module.exports = { extends: [require.resolve('@jutro/build-tools/eslint-strict-config/index')], };`
.eslintrc después	`module.exports = { extends: ['@jutro'], };`

.stylelintrc
.stylelintrc antes	`{ "extends": "@jutro/build-tools/stylelint-config/index" }`
.stylelintrc después	`{ "extends": "@jutro/stylelint-config" }`

@jutro/eslint-config agrega reglas adicionales además de las @jutro/build-tools preestablecidas (2 de gravedad de error, 1 de advertencia).

    rules: {
        'react/prop-types': ['error'],
        'max-params': ['warn', 3],
        'jutro-platform/metadata-jsx-i18n': 'error',
    },

Si desea ser totalmente compatible con las reglas obsoletas definidas en el paquete @jutro/build-tools, deshabilítelas.

Si está migrando desde @jutro/build-tools/eslint-config/index menos estricto y desea ser totalmente compatible con las configuraciones de reglas obsoletas, es posible que deba invalidar las reglas adicionales.

{
    extends: ['@jutro'],
    rules: {
        ...
        'unicorn/filename-case': 'warn',
    },
}

Note: Si el proyecto utiliza configuraciones de @jutro/build-tools que no sean de linting, como formateadores, es posible que aún se necesite esta dependencia. Como opción, defina estas configuraciones al nivel de la aplicación, que es el método recomendado.

Descripción general de la solución de linting​

Aspectos clave de la configuración de linting de Jutro​

Cómo se proporcionan las configuraciones de linting​

Configuración de ESLint​

Reglas de ESLint​

Configuración de Stylelint​

Reglas de Stylelint​

Cómo usar los linters​

Archivos de configuración​

Configuración de los linters​

Ejecución de linters con la CLI de Jutro​

Ejemplos de configuración​

Configuración predeterminada​

Estándares en la nube como errores​

Invalidaciones de reglas personalizadas​

Opciones de personalización​

Deshabilitación de una regla específica​

Cambio de la gravedad de la regla​

Configuración de las opciones de la regla​

Validación de estándares de la nube​

Reglas de estándares de la nube​

Ajustes preestablecidos de estándares de la nube​

ESLint​

Stylelint​

Requisitos​

Configuraciones de ejemplo​

Deshabilitación de reglas individuales​

Migración desde el paquete de herramientas de compilación​

Descripción general de la solución de linting

Aspectos clave de la configuración de linting de Jutro

Cómo se proporcionan las configuraciones de linting

Configuración de ESLint

Reglas de ESLint

Configuración de Stylelint

Reglas de Stylelint

Cómo usar los linters

Archivos de configuración

Configuración de los linters

Ejecución de linters con la CLI de Jutro

Ejemplos de configuración

Configuración predeterminada

Estándares en la nube como errores

Invalidaciones de reglas personalizadas

Opciones de personalización

Deshabilitación de una regla específica

Cambio de la gravedad de la regla

Configuración de las opciones de la regla

Validación de estándares de la nube

Reglas de estándares de la nube

Ajustes preestablecidos de estándares de la nube

ESLint

Stylelint

Requisitos

Configuraciones de ejemplo

Deshabilitación de reglas individuales

Migración desde el paquete de herramientas de compilación