protolint-mcp

by yoheimuta

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

protolint --mcp

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 .

brew tap yoheimuta/protolint brew install 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.

❯❯❯ docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint _example/proto [_example/proto/invalidFileName.proto:1:1] File name should be lower_snake_case.proto. [_example/proto/issue_88/oneof_options.proto:11:5] Found an incorrect indentation style " ". " " is correct. [_example/proto/issue_88/oneof_options.proto:12:5] Found an incorrect indentation style " ". " " is correct.

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.

go install github.com/yoheimuta/protolint/cmd/protolint@latest

Dentro de JavaScript / TypeScript

Puedes usar protolint usando tu administrador de paquetes nodejs como npm o yarn .

$ npm install protolint --save-dev

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 entornoValor predeterminadoDescripción
PROTOLINT_MIRROR_HOSThttps://github.comURL base del servidor web/HTTP que aloja los binarios
RUTA REMOTA DEL ESPEJO DE PROTOLINTyoheimuta/protolint/descargas/lanzamientosRuta a los archivos en el host remoto
PROTOLINT_MIRROR_NOMBRE_USUARIONombre de usuario de autenticación básica HTTP
CONTRASEÑA DE PROTOLINT_MIRRORContraseña de autenticación básica HTTP
PROTOLINT_PROXYProxy 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.

{ ... "scripts": { "protoc": "....", "preprotoc": "npx protolint" }, ... }

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 lint example.proto example2.proto # file mode, specify multiple specific files protolint lint . # directory mode, search for all .proto files recursively protolint . # same as "protolint lint ." protolint lint -config_path=path/to/your_protolint.yaml . # use path/to/your_protolint.yaml protolint lint -config_dir_path=path/to . # search path/to for .protolint.yaml protolint lint -fix . # automatically fix some of the problems reported by some rules protolint lint -fix -auto_disable=next . # this is preferable when you want to fix problems while maintaining the compatibility. Automatically fix some problems and insert disable comments to the other problems. The available values are next and this. protolint lint -auto_disable=next . # automatically insert disable comments to the other problems. protolint lint -v . # with verbose output to investigate the parsing error protolint lint -no-error-on-unmatched-pattern . # exits with success code even if no file is found (file & directory mode) protolint lint -reporter junit . # output results in JUnit XML format protolint lint -output_file=path/to/out.txt # output results to path/to/out.txt protolint lint -plugin ./my_custom_rule1 -plugin ./my_custom_rule2 . # run custom lint rules. protolint list # list all current lint rules being used protolint version # print protolint version protolint --version # print protolint version (global flag) protolint -v # print protolint version (when used as the only argument)

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:

repos: - repo: https://github.com/yoheimuta/protolint rev: <version> # Select a release here like v0.44.0 hooks: - id: protolint

o alternativamente use esto para ejecutar protolint con Docker:

repos: - repo: https://github.com/yoheimuta/protolint rev: <version> # Select a release here like v0.44.0 hooks: - id: protolint-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

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:

AmbienteValor de la línea de comandosDescripciónEjemplo
Acciones de Githubci-ghAyuda 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 DevOpsci-azAyuda 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/CDci-glabIngeniería inversa a partir de ejemplosWARNING: 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 entornoPrioridadSignificado
CADENA DE PLANTILLA DE PROTOLINT_CIREPORTER1Cadena que contiene una plantilla Go
ARCHIVO DE PLANTILLA DE PROTOLINT_CIREPORTER2Ruta 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 > ).

$ protolint --reporter ci-gh --add-reporter sarif:/path/to/my/output.sarif.json proto/*.proto

Ú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.

args := []string{"-config_path", "path/to/your_protolint.yaml", "."} var stdout bytes.Buffer var stderr bytes.Buffer err := lib.Lint(test.inputArgs, &stdout, &stderr)

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 .
OficialFijableDesactivación automáticaIDENTIFICACIÓNObjetivo
PREFIJO DE NOMBRES DE CAMPOS DE ENUMERACIÓNVerifica que los nombres de los campos de enumeración tengan como prefijo ENUM_NAME_UPPER_SNAKE_CASE.
NOMBRES DE CAMPOS DE ENUMERACIÓN EN MAYÚSCULASVerifica que todos los nombres de campos de enumeración sean MAYÚSCULAS CON GUIONES BAJOS.
NOMBRES DE CAMPOS DE ENUMERACIÓN CON VALOR CERO FINALIZAN CONVerifica 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 .
NOMBRES DE ENUMERACIÓN EN MAYÚSCULAS CAMELVerifica que todos los nombres de enumeración sean CamelCase (con mayúscula inicial).
*1NOMBRES DE ARCHIVOS EN MINÚSCULAS DE SERPIENTEVerifica que todos los nombres de archivo sean lower_snake_case.proto. Puedes configurar los archivos excluidos con .protolint.yaml .
NOMBRES DE CAMPO EN MINÚSCULAS DE SERPIENTEVerifica que todos los nombres de campo estén separados por guiones bajos.
*1IMPORTACIONES_CLASIFICADASVerifica que todas las importaciones estén ordenadas.
NOMBRES DE MENSAJES EN MAYÚSCULASVerifica que todos los nombres de los mensajes estén en CamelCase (con mayúscula inicial).
*1ORDENVerifica que todos los archivos se ordenen de la manera específica.
*1NOMBRE DEL PAQUETE EN MINÚSCULASVerifica que el nombre del paquete sólo debe contener letras minúsculas.
RPC_NAMES_UPPER_CAMEL_CASEVerifica que todos los nombres de rpc sean CamelCase (con mayúscula inicial).
NOMBRES DE SERVICIO EN MAYÚSCULASVerifica que todos los nombres de servicios sean CamelCase (con mayúscula inicial).
NOMBRES DE CAMPOS REPETIDOS EN PLURALIZACIÓNVerifica que los nombres de campos repetidos sean nombres pluralizados.
*1COTIZACIÓN CONSISTENTEVerifica que el uso de comillas para cadenas sea consistente. El valor predeterminado es comillas dobles. Puede configurar la comilla específica con .protolint.yaml .
*1SANGRARAplica 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 .
*1PROTO3_CAMPOS_EVITAR_REQUERIDOSVerifica que todos los campos deben evitar ser obligatorios para proto3.
_PROTO3_GRUPOS_EVITARVerifica que se deben evitar todos los grupos para proto3.
_*1LONGITUD MÁXIMA DE LÍNEAAplica 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 CONAplica un sufijo consistente para los nombres de servicio. Puedes configurar el sufijo específico con .protolint.yaml .
No_-LOS NOMBRES DE CAMPO EXCLUYEN PREPOSICIONESVerifica 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 PREPOSICIONESVerifica 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_CASEVerifica 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 COMENTARIOVerifica que todos los mensajes tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml .
No_-SERVICIOS_TIENEN_COMENTARIOVerifica que todos los servicios tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml .
No_-RPCS_TIENE_COMENTARIOVerifica que todos los RP tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml .
No_-LOS CAMPOS TIENEN COMENTARIOVerifica que todos los campos tengan un comentario. Puedes configurarlo para aplicar comentarios de estilo Golang con .protolint.yaml .
No_-LAS ENUMERACIONES TIENEN COMENTARIOVerifica 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 COMENTARIOVerifica 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 COMENTARIOVerifica que un archivo comience con un comentario de documentación.
No_-SINTAXIS_CONSISTENTEVerifica 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

enum FooBar { - UNSPECIFIED = 0; + FOO_BAR_UNSPECIFIED = 0; }

NOMBRES DE CAMPOS DE ENUMERACIÓN EN MAYÚSCULAS

enum Foo { - firstValue = 0; + FIRST_VALUE = 0; - second_value = 1; + SECOND_VALUE = 1; }

NOMBRES DE CAMPOS DE ENUMERACIÓN CON VALOR CERO FINALIZAN CON

enum Foo { - FOO_FIRST = 0; + FOO_UNSPECIFIED = 0; }

NOMBRES DE ENUMERACIÓN EN MAYÚSCULAS CAMEL

- enum foobar { + enum FooBar { FIRST_VALUE = 0; SECOND_VALUE = 1; }

NOMBRES DE CAMPO EN MINÚSCULAS DE SERPIENTE

message SongServerRequest { - required string SongName = 1; + required string song_name = 1; }

IMPORTACIONES_CLASIFICADAS

- import public "new.proto"; + import "myproject/other_protos.proto"; - import "myproject/other_protos.proto"; + import public "new.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/timestamp.proto";

NOMBRES DE MENSAJES EN MAYÚSCULAS

- message song_server_request { + message SongServerRequest { required string SongName = 1; required string song_name = 1; }

ORDEN

- option java_package = "com.example.foo"; - syntax = "proto3"; - package examplePb; - message song_server_request { } - import "other.proto"; + syntax = "proto3"; + package examplePb; + import "other.proto"; + option java_package = "com.example.foo"; + message song_server_request { }

NOMBRE DEL PAQUETE EN MINÚSCULAS

- package myPackage + package my.package

RPC_NAMES_UPPER_CAMEL_CASE

service FooService { - rpc get_something(FooRequest) returns (FooResponse); + rpc GetSomething(FooRequest) returns (FooResponse); }

RPC_NAMES_UPPER_CAMEL_CASE

- service foo_service { + service FooService { rpc get_something(FooRequest) returns (FooResponse); rpc GetSomething(FooRequest) returns (FooResponse); }

NOMBRES DE CAMPOS REPETIDOS EN PLURALIZACIÓN

- repeated string song_name = 1; + repeated string song_names = 1;

SANGRAR

enum enumAllowingAlias { UNKNOWN = 0; - option allow_alias = true; + option allow_alias = true; STARTED = 1; - RUNNING = 2 [(custom_option) = "hello world"]; + RUNNING = 2 [(custom_option) = "hello world"]; - } +}
- message TestMessage { string test_field = 1; } + message TestMessage { + string test_field = 1; +}

COTIZACIÓN CONSISTENTE

option java_package = "com.example.foo"; - option go_package = 'example'; + option go_package = "example";

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:

// protolint:disable <ruleID1> [<ruleID2> <ruleID3>...] ... // protolint:enable <ruleID1> [<ruleID2> <ruleID3>...]

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:

enum Foo { // protolint:disable:next ENUM_FIELD_NAMES_UPPER_SNAKE_CASE firstValue = 0; // no error second_value = 1; // protolint:disable:this ENUM_FIELD_NAMES_UPPER_SNAKE_CASE THIRD_VALUE = 2; // spits out an error }

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.

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:

bash release.sh <version> [message]

Licencia

La Licencia MIT (MIT)

Related MCP Servers

  • A
    security
    A
    license
    A
    quality
    dbt-mcp
    Last updated -
    16
    182
    Python
    Apache 2.0
    • Linux
    • Apple
  • A
    security
    A
    license
    A
    quality
    interactive-mcp
    Last updated -
    5
    705
    29
    TypeScript
    MIT License
    • Apple
    • Linux

View all related MCP servers

ID: n36s0xdbks