Tus TODOs, con fecha límite. Y con consecuencias.

Wisemark es un estándar simple y potente para gestionar los comentarios de tu código. Permite:

1. Hacer seguimiento de tus TODOs, FIXMEs y otros comentarios en el código.
2. Establecer fechas límite para tus TODOs y FIXMEs.
3. Fallar pipelines si tienes comentarios vencidos.
4. Generar informes de tus comentarios.

¿Nunca has encontrado comentarios olvidados en código legacy? ¿O has tenido que lidiar con un TODO que nunca se hizo? Wisemark está aquí para ayudarte.

Uso principal:

// @question What if the numbers are negative?
function sum(a: number, b: number): number {
  // @todo Add a test for negative numbers
  return a + b;
}

Usando los tipos principales:

Wisemark detectará automáticamente estos comentarios y te permitirá gestionarlos. Esta es la salida habitual usando la extensión de VSCode.

Paquetes

• @wisemark/core: La librería principal de Wisemark. Proporciona la funcionalidad principal y la API para gestionar comentarios.
• @wisemark/cli: La interfaz de línea de comandos de Wisemark. Permite ejecutar comandos de Wisemark desde el terminal.
• @wisemark/vscode: La extensión de VSCode para Wisemark. Proporciona una interfaz de usuario para gestionar comentarios directamente en el editor.

Crear comentarios Wisemark

Un comentario puede ser tan simple como:

// @<tipo> <mensaje>

Ejemplos:

// @todo Add a test for negative numbers
// @fixme Fix the bug in the code
// @note This is a note
// @question What if the numbers are negative?
// @refactor Refactor this function

Se pueden añadir parámetros opcionales al comentario:

• severity: low, medium, high
• tags: cualquier cadena separada por comas
• author: el autor del comentario
• due: la fecha límite del comentario (YYYY-MM-DD)
• id: un nombre único para el comentario (se genera automáticamente, pero puedes sobreescribirlo)

Estructura del comentario:

// @<tipo> <mensaje> -- severity: <severity> -- tags: <tags> -- author: <author> -- due: <due> -- id: <id>

// @todo Add a test for negative numbers -- severity: high -- tags: bug, urgent -- author: Pol Gubau -- due: 2023-10-01 -- id: test-negative-numbers

// @fixme Fix the bug in the code -- severity: medium -- tags: bug,correct

Herramienta CLI

Wisemark CLI es una herramienta de línea de comandos que te permite gestionar tus comentarios directamente desde el terminal. Proporciona comandos para escanear tu codebase, generar informes y gestionar tus TODOs y FIXMEs. (La generación de informes aún no está implementada)

Instalación remota o local

Ejecución remota

Si no quieres instalar Wisemark en tu ordenador, ejecuta el siguiente comando en tu terminal:

npx @wisemark/cli

Instalación local

Puedes instalar Wisemark CLI globalmente usando npm:

npm install -g @wisemark/cli

Uso

Una vez instalado, puedes usar los siguientes comandos:

Escanear comandos Wisemark

Este comando escanea tu codebase en busca de comentarios Wisemark y genera un informe de todos los TODOs, FIXMEs y otros comentarios. Se puede activar con el comando por defecto wisemark o wisemark scan.

wisemark [options]

wisemark lint [options]

Opciones

Para ambos comandos puedes usar las siguientes opciones:

Las opciones disponibles son:

• --type: Filtrar por tipo (todo, note, fixme)
• --path: Ruta interna del proyecto a escanear (por defecto: .)
• --severity: Filtrar por severidad (low, medium, high)
• --json: Devolver la salida en formato JSON
• --table: Devolver la salida en formato tabla
• --showDate: Mostrar la fecha del comentario
• --withDueDate: Devolver solo comentarios con fecha límite
• --due: Filtrar por fecha límite (YYYY-MM-DD)
• --tags: Filtrar por etiquetas (separadas por comas)
• --cwd: Ruta del proyecto (por defecto: directorio de trabajo actual)
• --help: Mostrar información de ayuda
• --version: Mostrar información de versión

Un ejemplo completo del comando sería:

wisemark --type todo --path src --severity high --json --showDate --withDueDate --due 2023-10-01 --tags bug,urgent

Extensión de VSCode

Wisemark es una extensión de VSCode que te ayuda a gestionar y escanear comandos inteligentes dentro de tu codebase. Permite insertar fácilmente diferentes tipos de comentarios (como TODO, FIXME, Notes, Questions, Refactors) y navegar y gestionar estos comentarios rápidamente. También proporciona coloreado de tokens mejorado y opciones de agrupación para una mejor organización del código.

Funcionalidades

• Inserción de comandos: Inserta comentarios predefinidos como:
  • Note
  • Todo
  • Fixme
  • Question
  • Refactor
• Escaneo de comandos: Escanea y gestiona tu proyecto en busca de comandos específicos con una funcionalidad de búsqueda rápida.
• Agrupación: Activa/desactiva la agrupación de comentarios para una mejor organización.
• Personalización de colores: Diferentes colores para cada tipo de comentario (Note, Todo, etc.) para distinguirlos visualmente.
• Menús contextuales: Accede a todos los comandos directamente desde el menú contextual del editor.
• Navegación rápida: Navega fácilmente entre comentarios y secciones de tu código.

Instalación

1. Abre VSCode.
2. Ve a la vista de Extensiones (Ctrl+Shift+X).
3. Busca Wisemark.
4. Haz clic en Install.

Alternativamente, puedes instalarlo desde el terminal:

ext install wisemark

Uso

Una vez instalado, podrás usar Wisemark para:

1. Insertar comentarios: Puedes insertar los siguientes comentarios en tu código:

   • Note: ctrl+alt+n
   • Todo: ctrl+alt+t
   • FIXME: ctrl+alt+f
   • Question: ctrl+alt+q
   • Refactor: ctrl+alt+r

2. Escaneo de comandos: Para escanear todos los comentarios, ejecuta el comando Scan Wisemark Commands desde la paleta de comandos (Ctrl+Shift+P > Scan Wisemark commands).

   

3. Agrupar comentarios: Activa la agrupación para una mejor visibilidad y organización de tus comentarios usando el comando Toggle Grouping.

   

4. Navegar entre comentarios: Usa el comando Select and Open a Comment para navegar rápidamente entre comentarios de tu código.

   

Configuración

Puedes personalizar los colores de los tokens para cada tipo de comentario. Por defecto, Wisemark usa los siguientes colores:

• Note: #ff6347 (cursiva)
• Todo: #e5c07b (negrita)
• FIXME: #f0f0f0 (cursiva)
• Refactor: #00bcd4 (negrita)
• Question: #8be9fd (cursiva)

Para personalizar, abre la configuración de VSCode y modifica "editor.tokenColorCustomizations" a tu gusto.

Funciones predictivas

Wisemark también predice los comentarios más usados según tu historial de uso, ayudándote a agilizar el proceso.

Quick Pick para comandos

Para insertar comentarios aún más rápido, usa la funcionalidad Quick Pick, que sugiere las mejores opciones para tu tarea actual.

Agrupar comentarios por tipo

Agrupa fácilmente tus comentarios por tipo para una mejor organización.

Hoja de ruta

Contribuir

Si quieres contribuir a Wisemark, no dudes en enviar issues y pull requests. ¡Las contribuciones son bienvenidas!

1. Haz un fork de este repositorio.
2. Crea tu rama (git checkout -b feature/tu-funcionalidad).
3. Realiza tus cambios (git commit -am 'Añadir nueva funcionalidad').
4. Sube a la rama (git push origin feature/tu-funcionalidad).
5. Abre un pull request.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

¡Disfruta organizando tu código y comentarios con Wisemark!