Integrations
Supports running protolint in GitHub workflows through various actions including github/super-linter, plexsystems/protolint-action, and yoheimuta/action-protolint
Supports JetBrains GoLand through the intellij-protolint plugin for Protocol Buffer linting
Integrates with JetBrains IDEs through the intellij-protolint plugin for Protocol Buffer linting
protolint
protolint es la utilidad conectable de corrección/reparación de pelusas para archivos de búfer de protocolo (proto2+proto3):
- Se ejecuta rápido porque funciona sin compilador.
- Guía de estilo oficial fácil de seguir. Las reglas y la guía de estilo se corresponden perfectamente.
- Fixer corrige automáticamente todas las posibles violaciones de la guía de estilo oficial.
- Permite deshabilitar reglas con un comentario en un archivo de búfer de protocolo.
- Es útil para proyectos que deben mantener la compatibilidad con la API y al mismo tiempo aplicar la guía de estilo tanto como sea posible.
- Algunas reglas se pueden desactivar automáticamente insertando comentarios en las infracciones detectadas.
- Carga complementos para contener sus reglas de pelusa personalizadas.
- Sometido a pruebas para todas las reglas.
- Muchos soportes de integración.
- complemento de protocolo
- Integración del editor
- Acción de GitHub
- Integración de CI
Manifestación
Una vez configurado el servidor MCP, puede pedirle a cualquier cliente MCP como Claude Desktop que revise y repare sus archivos de búfer de protocolo de la siguiente manera:
Además, vim-protolint funciona de la siguiente manera.
Servidor MCP
protolint ahora incluye soporte para el Protocolo de Contexto de Modelo (MCP) , que permite que los modelos de IA interactúen con protolint directamente.
Uso
Para obtener documentación detallada sobre cómo utilizar e integrar la funcionalidad del servidor MCP de protolint, consulte la documentación de MCP .
Instalación
Vía Homebrew
protolint se puede instalar para Mac o Linux usando Homebrew a través del grifo yoheimuta/protolint .
Dado que homebrew-core incluye protolint,
también puedes instalarlo simplemente con brew install protolint.
Este es el tap predeterminado que se instala. Es más sencillo, pero no lo mantiene el mismo autor. Para mantenerlo actualizado, te recomiendo ejecutar primero brew tap yoheimuta/protolint
.
A través de lanzamientos de GitHub
También puedes descargar un binario prediseñado desde esta página de lanzamiento:
En la sección de descargas de cada versión, puedes encontrar binarios prediseñados en paquetes .tar.gz.
Utilice la imagen de Docker mantenida
protolint envía una imagen de Docker yoheimuta/protolint que le permite usar protolint como parte de su flujo de trabajo de Docker.
De la fuente
El binario se puede instalar desde el código fuente si Go está disponible. Sin embargo, recomiendo usar uno de los binarios precompilados, ya que no incluye la información de la versión.
Dentro de JavaScript / TypeScript
Puedes usar protolint
usando tu administrador de paquetes nodejs como npm
o yarn
.
Esto agregará una referencia a una dependencia de desarrollo a su package.json
local.
Durante la instalación, se ejecutará el script install.mjs . Este descargará el protolint
correspondiente desde GitHub. Al igual que con @electron/get , puedes omitir la descarga usando las siguientes variables de entorno:
Variable de entorno | Valor predeterminado | Descripción |
---|---|---|
PROTOLINT_MIRROR_HOST | https://github.com | URL base del servidor web/HTTP que aloja los binarios |
RUTA REMOTA DEL ESPEJO DE PROTOLINT | yoheimuta/protolint/descargas/lanzamientos | Ruta a los archivos en el host remoto |
PROTOLINT_MIRROR_NOMBRE_USUARIO | Nombre de usuario de autenticación básica HTTP | |
CONTRASEÑA DE PROTOLINT_MIRROR | Contraseña de autenticación básica HTTP | |
PROTOLINT_PROXY | Proxy HTTP(S) con datos de autenticación opcionales |
Dentro de la ruta remota, se deben reflejar los archivos de la página de versiones .
Después de eso, puedes usar npx protolint
(con todos los argumentos protolint suministrados) dentro de tus scripts de desarrollo.
Puede agregar un nodo protolint
a su package.json
que puede contener el contenido de protolint.yml
debajo del nodo lint
, es decir, el elemento raíz de la configuración será protolint
.
Si desea obtener una salida que coincida con el compilador TSC, utilice el reportero tsc
.
Dentro de los proyectos de Python
Puedes usar protolint
como linter en tus proyectos de Python. El archivo wheel protolint-bin
de pypi contiene los binarios precompilados para diversas plataformas. Simplemente añade la versión deseada a tu pyproject.toml
o requirements.txt
.
Las ruedas descargadas contendrán los binarios compilados de Go para protolint
y protoc-gen-protolint
. Su plataforma debe ser compatible con las plataformas de binarios compatibles.
Puede agregar la configuración del linter al paquete tools.protolint
en pyproject.toml
.
Uso
protolint no requiere configuración por defecto, para la mayoría de proyectos debería funcionar de inmediato.
Integración del control de versiones
Protolint está disponible como un gancho pre-commit . Añádelo a tu archivo .pre-commit-config.yaml
en tu repositorio para ejecutar Protolint con Go:
o alternativamente use esto para ejecutar protolint con Docker:
Integración del editor
Código de Visual Studio
JetBrains IntelliJ IDEA, GoLand, WebStorm, PHPStorm, PyCharm...
Vim ( motor ALE )
Vim ( Sintástico )
Acción de GitHub
Una acción de GitHub para ejecutar protolint en sus flujos de trabajo
Integración de CI
Complementos de Jenkins
- advertencias-ng y cualquiera que use violatons-lib
Salida específica del entorno
Es posible formatear el linting según el formato del entorno de CI/CD. El entorno debe configurarse utilizando el formato de salida. Actualmente, se obtiene la siguiente salida:
Ambiente | Valor de la línea de comandos | Descripción | Ejemplo |
---|---|---|---|
Acciones de Github | ci-gh | Ayuda de Github | ::warning file=example.proto,line=10,col=20,title=ENUM_NAMES_UPPER_CAMEL_CASE::EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES |
Azure DevOps | ci-az | Ayuda de Azure DevOps | ##vso[task.logissue type=warning;sourcepath=example.proto;linenumber=10;columnnumber=20;code=ENUM_NAMES_UPPER_CAMEL_CASE;]EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES |
Gitlab CI/CD | ci-glab | Ingeniería inversa a partir de ejemplos | WARNING: ENUM_NAMES_UPPER_CAMEL_CASE example.proto(10,20) : EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES |
También puede utilizar el formateador ci
genérico, que creará un comparador de problemas genérico.
Con el valor ci-env
, puede especificar la plantilla de las siguientes variables de entorno:
Variable de entorno | Prioridad | Significado |
---|---|---|
CADENA DE PLANTILLA DE PROTOLINT_CIREPORTER | 1 | Cadena que contiene una plantilla Go |
ARCHIVO DE PLANTILLA DE PROTOLINT_CIREPORTER | 2 | Ruta a un archivo que contiene una plantilla Go |
No se debe agregar el salto de línea resultante, ya que se agregará automáticamente.
Los siguientes campos están disponibles:
Severity
: La gravedad como cadena (nota, advertencia o error)
File
: Ruta al archivo que contiene el error
Line
: Línea dentro del file
que contiene el error (posición inicial)
Column
: Columna dentro del file
que contiene el error (posición inicial)
Rule
: El nombre de la regla que falla
Message
: El mensaje de error que describe el error.
Producción de un archivo de salida y un flujo de error de CI/CD
Puede crear una salida específica que coincida con su entorno CI/CD y también crear un archivo de salida, por ejemplo, para sus herramientas de análisis de código estático como Github CodeQL o SonarQube.
Esto se puede hacer añadiendo el indicador --add-reporter
. Tenga en cuenta que el valor debe tener el formato <reporter-name>:<output-file-path>
(omitiendo <
y >
).
Úselo como complemento de protocolo
Protolint también mantiene un binario protoc-gen-protolint que realiza la función de lint como complemento de protocolo. Consulte cmd/protoc-gen-protolint/README.md para más detalles.
Esto es útil en situaciones en las que ya tienes un flujo de trabajo de complemento de protocolo.
Llamada desde el código Go
También puedes usar protolint desde el código de Go. Consulta la documentación de Go y lib/lint_test.go para más detalles.
Normas
Ver internal/addon/rules
en detalle.
El conjunto de reglas es el siguiente:
- Guía de estilo oficial . Está habilitada por defecto. Básicamente, estas reglas pueden corregir las infracciones añadiendo la opción
-fix
. - Guía de estilo no oficial. Está deshabilitada por defecto. Puedes habilitar cada regla con
.protolint.yaml
.
La opción -fix
en la línea de comandos puede corregir automáticamente todos los problemas reportados por las reglas corregibles. Consulte las columnas "Corregibles" a continuación.
La opción -auto_disable
en la línea de comandos puede deshabilitar automáticamente todos los problemas reportados por las reglas de deshabilitación automática. Esta función es útil cuando la corrección de infracciones existentes afecta la compatibilidad. Consulte las columnas de deshabilitación automática a continuación.
- *1: Estas reglas no deberían ser compatibles con la función de deshabilitación automática, ya que las correcciones no afectan su compatibilidad. Debe ejecutar el protocolo con
-fix
.
Oficial | Fijable | Desactivación automática | IDENTIFICACIÓN | Objetivo |
---|---|---|---|---|
Sí | ✅ | ✅ | PREFIJO DE NOMBRES DE CAMPOS DE ENUMERACIÓN | Verifica que los nombres de los campos de enumeración tengan como prefijo ENUM_NAME_UPPER_SNAKE_CASE. |
Sí | ✅ | ✅ | NOMBRES DE CAMPOS DE ENUMERACIÓN EN MAYÚSCULAS | Verifica que todos los nombres de campos de enumeración sean MAYÚSCULAS CON GUIONES BAJOS. |
Sí | ✅ | ✅ | NOMBRES DE CAMPOS DE ENUMERACIÓN CON VALOR CERO FINALIZAN CON | Verifica que la enumeración con valor cero deba tener el sufijo (p. ej., "SIN ESPECIFICAR", "INVÁLIDO"). El valor predeterminado es "SIN ESPECIFICAR". Puede configurar el sufijo específico con .protolint.yaml . |
Sí | ✅ | ✅ | NOMBRES DE ENUMERACIÓN EN MAYÚSCULAS CAMEL | Verifica que todos los nombres de enumeración sean CamelCase (con mayúscula inicial). |
Sí | ✅ | *1 | NOMBRES DE ARCHIVOS EN MINÚSCULAS DE SERPIENTE | Verifica que todos los nombres de archivo sean lower_snake_case.proto. Puedes configurar los archivos excluidos con .protolint.yaml . |
Sí | ✅ | ✅ | NOMBRES DE CAMPO EN MINÚSCULAS DE SERPIENTE | Verifica que todos los nombres de campo estén separados por guiones bajos. |
Sí | ✅ | *1 | IMPORTACIONES_CLASIFICADAS | Verifica que todas las importaciones estén ordenadas. |
Sí | ✅ | ✅ | NOMBRES DE MENSAJES EN MAYÚSCULAS | Verifica que todos los nombres de los mensajes estén en CamelCase (con mayúscula inicial). |
Sí | ✅ | *1 | ORDEN | Verifica que todos los archivos se ordenen de la manera específica. |
Sí | ✅ | *1 | NOMBRE DEL PAQUETE EN MINÚSCULAS | Verifica que el nombre del paquete sólo debe contener letras minúsculas. |
Sí | ✅ | ✅ | RPC_NAMES_UPPER_CAMEL_CASE | Verifica que todos los nombres de rpc sean CamelCase (con mayúscula inicial). |
Sí | ✅ | ✅ | NOMBRES DE SERVICIO EN MAYÚSCULAS | Verifica que todos los nombres de servicios sean CamelCase (con mayúscula inicial). |
Sí | ✅ | ✅ | NOMBRES DE CAMPOS REPETIDOS EN PLURALIZACIÓN | Verifica que los nombres de campos repetidos sean nombres pluralizados. |
Sí | ✅ | *1 | COTIZACIÓN CONSISTENTE | Verifica que el uso de comillas para cadenas sea consistente. El valor predeterminado es comillas dobles. Puede configurar la comilla específica con .protolint.yaml . |
Sí | ✅ | *1 | SANGRAR | Aplica un estilo de sangría consistente. El estilo predeterminado es de 2 espacios. La inserción de nuevas líneas también está forzada por defecto. Puede configurar los detalles con .protolint.yaml . |
Sí | ✅ | *1 | PROTO3_CAMPOS_EVITAR_REQUERIDOS | Verifica que todos los campos deben evitar ser obligatorios para proto3. |
Sí | _ | ✅ | PROTO3_GRUPOS_EVITAR | Verifica que se deben evitar todos los grupos para proto3. |
Sí | _ | *1 | LONGITUD MÁXIMA DE LÍNEA | Aplica una longitud máxima de línea. La longitud de una línea se define como el número de caracteres Unicode que contiene. El valor predeterminado es 80 caracteres. Puede configurar los detalles con .protolint.yaml . |
No | _ | - | LOS NOMBRES DE SERVICIO TERMINAN CON | Aplica un sufijo consistente para los nombres de servicio. Puedes configurar el sufijo específico con .protolint.yaml . |
No | _ | - | LOS NOMBRES DE CAMPO EXCLUYEN PREPOSICIONES | Verifica que los nombres de campo no incluyan preposiciones (p. ej., "para", "durante", "en"). Puedes configurar las preposiciones específicas y las palabras clave excluidas con .protolint.yaml . |
No | _ | - | LOS NOMBRES DE LOS MENSAJES EXCLUYEN LAS PREPOSICIONES | Verifica que los nombres de los mensajes no incluyan preposiciones (p. ej., "Con", "Para"). Puedes configurar las preposiciones específicas y las palabras clave excluidas con .protolint.yaml . |
No | _ | - | RPC_NAMES_CASE | Verifica que todos los nombres de rpc cumplan con la convención especificada. Debe configurar la convención específica con .protolint.yaml . |
No | _ | - | LOS MENSAJES TIENEN COMENTARIO | Verifica que todos los mensajes tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml . |
No | _ | - | SERVICIOS_TIENEN_COMENTARIO | Verifica que todos los servicios tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml . |
No | _ | - | RPCS_TIENE_COMENTARIO | Verifica que todos los RP tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml . |
No | _ | - | LOS CAMPOS TIENEN COMENTARIO | Verifica que todos los campos tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml . |
No | _ | - | LAS ENUMERACIONES TIENEN COMENTARIO | Verifica que todas las enumeraciones tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml . |
No | _ | - | LOS CAMPOS DE ENUMERACIÓN TIENEN COMENTARIO | Verifica que todos los campos de enumeración tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml . |
No | _ | - | EL ARCHIVO TIENE UN COMENTARIO | Verifica que un archivo comience con un comentario de documentación. |
No | _ | - | SINTAXIS_CONSISTENTE | Verifica que la sintaxis corresponda a una versión específica. El valor predeterminado es proto3. Puede configurar la versión con .protolint.yaml . |
Le recomiendo que agregue all_default: true
en .protolint.yaml
, porque todos los linters anteriores se habilitan automáticamente para que siempre pueda disfrutar de los máximos beneficios cada vez que se actualice protolint.
A continuación se muestran algunos ejemplos que muestran un buen estilo habilitado de forma predeterminada. -
es un mal estilo, +
es un buen estilo:
PREFIJO DE NOMBRES DE CAMPOS DE ENUMERACIÓN
NOMBRES DE CAMPOS DE ENUMERACIÓN EN MAYÚSCULAS
NOMBRES DE CAMPOS DE ENUMERACIÓN CON VALOR CERO FINALIZAN CON
NOMBRES DE ENUMERACIÓN EN MAYÚSCULAS CAMEL
NOMBRES DE CAMPO EN MINÚSCULAS DE SERPIENTE
IMPORTACIONES_CLASIFICADAS
NOMBRES DE MENSAJES EN MAYÚSCULAS
ORDEN
NOMBRE DEL PAQUETE EN MINÚSCULAS
RPC_NAMES_UPPER_CAMEL_CASE
RPC_NAMES_UPPER_CAMEL_CASE
NOMBRES DE CAMPOS REPETIDOS EN PLURALIZACIÓN
SANGRAR
COTIZACIÓN CONSISTENTE
Creando tus reglas personalizadas
protolint es un linter conectable que le permite crear libremente reglas de lint personalizadas.
Se incluye un proyecto de muestra completo (también conocido como complemento) en este repositorio en el directorio _example/plugin .
Reporteros
protolint viene con varios reporteros incorporados (también conocidos como formateadores) para controlar la apariencia de los resultados del pelusa.
Puede especificar un reportero usando el indicador -reporter en la línea de comandos. Por ejemplo, -reporter junit
usa el reportero junit.
Las opciones del reportero incorporado son:
- simple (predeterminado)
- junit
- json
- sarif
- sonar (formato de problema genérico de SonarQube)
- Unix
- tsc (compatible con el compilador TypeScript)
Configuración
Deshabilitar reglas en un archivo de búfer de protocolo
Las reglas se pueden deshabilitar mediante un comentario dentro de un archivo de búfer de protocolo con el siguiente formato. Las reglas se deshabilitarán hasta el final del archivo o hasta que el linter detecte un comentario de habilitación coincidente:
También es posible modificar un comando de desactivación agregando :next o :this para aplicar el comando solo a esta (actual) o a la siguiente línea respectivamente.
Por ejemplo:
Establecer la opción de línea de comandos -auto_disable
en next
o this
inserta comandos de desactivación siempre que se detecten problemas.
Puede especificar la opción -fix
simultáneamente. Las reglas que admiten auto_disable suprimen las infracciones en lugar de corregirlas, lo que provoca una incompatibilidad de esquema.
Archivo de configuración
protolint puede funcionar utilizando un archivo de configuración llamado .protolint.yaml
.
Consulte _example/config/.protolint.yaml para obtener la especificación del archivo de configuración.
De forma predeterminada, protolint buscará automáticamente el archivo de configuración en el directorio de trabajo actual y en los directorios superiores sucesivos hasta el directorio raíz del sistema de archivos. Puede buscar en el directorio especificado con el indicador -config_dir_path
. También puede buscar en el archivo especificado con el indicador --config_path
.
Códigos de salida
Al analizar archivos, protolint saldrá con uno de los siguientes códigos de salida:
0
: El análisis de linting fue exitoso y no hay errores de linting.1
: El linting fue exitoso y hay al menos un error de linting.2
: El análisis no tuvo éxito debido a otros errores, como errores de análisis, internos y de tiempo de ejecución.
Motivación
Existen linters protobuf similares a partir del 20/12/2018.
Uno es un complemento para el compilador Protocol Buffers de Google.
- Cuando simplemente desea depurar los archivos, puede resultar tedioso crear el entorno de compilación.
- Y generalmente lleva mucho más tiempo compilar los archivos que analizarlos.
Otra es una herramienta de línea de comandos que también analiza los archivos de Protocol Buffer.
- Si bien tiene muchas otras funciones además de la pelusa, parece engorroso para los usuarios que solo quieren la pelusa.
- La regla de la pelusa tiende a ser obstinada.
- Además, el conjunto de reglas y la guía de estilo oficial no se corresponden exactamente. Es necesario comprender tanto las reglas como la guía en detalle y, posteriormente, combinarlas con precisión.
Otras herramientas
El 17/12/2019 escribí un artículo comparando varios Protocol Buffer Linters, incluido protolint.
- https://qiita.com/yoheimuta/items/da7678fcd046b93a2637
- NOTA: Éste está escrito en japonés.
Dependencias
Desarrollo
Liberar
Para agilizar el proceso de lanzamiento y reducir los errores humanos, se incluye un script release.sh
en el repositorio. Este script automatiza los pasos necesarios para crear y enviar una nueva etiqueta de lanzamiento.
Cómo utilizar
Ejecute el siguiente comando para crear una nueva versión:
Licencia
La Licencia MIT (MIT)
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
protolint-mcp
- Manifestación
- Servidor MCP
- Instalación
- Uso
- Integración del control de versiones
- Integración del editor
- Acción de GitHub
- Integración de CI
- Úselo como complemento de protocolo
- Llamada desde el código Go
- Normas
- Creando tus reglas personalizadas
- Reporteros
- Configuración
- Códigos de salida
- Motivación
- Dependencias
- Desarrollo
- Licencia
Related MCP Servers
- GoMIT License
- PythonApache 2.0
- Rust
- TypeScriptMIT License