Els teus TODOs, amb termini. I conseqüències.

Wisemark és un estàndard senzill i potent per gestionar els comentaris del teu codi. Permet:

1. Fer el seguiment dels teus TODOs, FIXMEs i altres comentaris al teu codi.
2. Establir terminis (deadlines) per als teus TODOs i FIXMEs.
3. Fer fallar les pipelines si tens comentaris vençuts.
4. Generar informes dels teus comentaris.

No t’has trobat mai comentaris oblidats en codi antic? O has hagut de lidiar amb un TODO que mai es va fer? Wisemark és aquí per ajudar-te.

Ús principal:

// @question I si els números són negatius?
function sum(a: number, b: number): number {
  // @todo Afegir un test per a números negatius
  return a + b;
}

Ús dels tipus principals:

Wisemark detectarà automàticament aquests comentaris i et permetrà gestionar-los. Aquesta és la sortida habitual utilitzant l’extensió de VSCode.

Paquets

• @wisemark/core: La llibreria principal de Wisemark. Proporciona la funcionalitat base i l’API per gestionar comentaris.
• @wisemark/cli: La interfície de línia de comandes per a Wisemark. Et permet executar comandes de Wisemark des del terminal.
• @wisemark/vscode: L’extensió de VSCode per a Wisemark. Proporciona una interfície d’usuari per gestionar comentaris directament a l’editor.

Creació de comentaris Wisemark

Un comentari pot ser tan senzill com:

// @<tipus> <missatge>

Exemples:

// @todo Afegir un test per a números negatius
// @fixme Arreglar el bug al codi
// @note Això és una nota
// @question I si els números són negatius?
// @refactor Refactoritzar aquesta funció

Es poden afegir alguns paràmetres opcionals al comentari:

• severity: low, medium, high
• tags: qualsevol cadena separada per comes
• author: l’autor del comentari
• due: la data de venciment del comentari (YYYY-MM-DD)
• id: un nom únic per al comentari (es genera automàticament però pots sobreescriure’l)

Estructura del comentari:

// @<tipus> <missatge> -- severity: <severitat> -- tags: <etiquetes> -- author: <autor> -- due: <venciment> -- id: <id>

// @todo Afegir un test per a números negatius -- severity: high -- tags: bug, urgent -- author: Pol Gubau -- due: 2023-10-01 -- id: test-negative-numbers

// @fixme Arreglar el bug al codi -- severity: medium -- tags: bug,correct

Eina CLI

Wisemark CLI és una eina de línia de comandes que et permet gestionar els teus comentaris directament des del terminal. Proporciona comandes per escanejar el teu codi, generar informes i gestionar els teus TODOs i FIXMEs. (La generació d’informes encara no està implementada)

Instal·lació remota o local

Execució remota

Si no vols instal·lar Wisemark al teu ordinador, només cal que executis la següent comanda al teu terminal:

npx @wisemark/cli

Instal·lació local

Pots instal·lar Wisemark CLI globalment mitjançant npm:

npm install -g @wisemark/cli

Ús

Un cop instal·lat, pots utilitzar les següents comandes:

Escanejar comandes de Wisemark

Aquesta comanda escaneja el teu codi a la recerca de comentaris de Wisemark i genera un informe de tots els TODOs, FIXMEs i altres comentaris. Es pot activar amb la comanda per defecte wisemark o wisemark scan.

wisemark [opcions]

wisemark lint [opcions]

Opcions

Per a aquestes dues comandes pots utilitzar les següents opcions:

Les opcions opcionals són:

• --type: Filtrar per tipus (todo, note, fixme)
• --path: Camí intern del projecte a escanejar (per defecte: .)
• --severity: Filtrar per severitat (low, medium, high)
• --json: Retornar la sortida en format JSON
• --table: Retornar la sortida en format taula
• --showDate: Mostrar la data del comentari
• --withDueDate: Retornar només els comentaris amb una data de venciment
• --due: Filtrar per data de venciment (YYYY-MM-DD)
• --tags: Filtrar per etiquetes (separades per comes)
• --cwd: Camí al projecte (per defecte: directori de treball actual)
• --help: Mostrar informació d’ajuda
• --version: Mostrar informació de la versió

Un exemple complet de la comanda seria:

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

Extensió de VSCode

Wisemark és una extensió de VSCode que t’ajuda a gestionar i escanejar comandes intel·ligents dins del teu codi. Permet la inserció fàcil de diferents tipus de comentaris (com TODO, FIXME, Notes, Preguntes, Refactoritzacions) i et permet navegar i gestionar ràpidament aquests comentaris. També proporciona un acolorit de tokens millorat i opcions d’agrupament per a una millor organització del codi.

Característiques

• Inserció de comandes: Insereix comentaris predefinits com:
  • Nota
  • Todo
  • Fixme
  • Pregunta
  • Refactorització
• Escaneig de comandes: Escaneja i gestiona el teu projecte per a comandes específiques amb una funcionalitat de cerca ràpida.
• Agrupament: Activa/desactiva l’agrupament de comentaris per a una millor organització.
• Personalització de colors: Diferents colors per a cada tipus de comentari (Nota, Todo, etc.) per fer els teus comentaris més distingibles visualment.
• Menús contextuals: Accedeix a totes les comandes directament des del menú contextual de l’editor.
• Navegació ràpida: Navega fàcilment entre comentaris i seccions del teu codi.

Instal·lació

1. Obre el VSCode.
2. Ves a la vista d’Extensions (Ctrl+Shift+X).
3. Busca Wisemark.
4. Fes clic a Instal·lar.

Alternativament, pots instal·lar-ho mitjançant el terminal:

ext install wisemark

Ús

Un cop instal·lat, podràs utilitzar Wisemark per:

1. Insertar comentaris: Pots inserir els següents comentaris al teu codi:

   • Nota: ctrl+alt+n
   • Todo: ctrl+alt+t
   • FIXME: ctrl+alt+f
   • Pregunta: ctrl+alt+q
   • Refactorització: ctrl+alt+r

2. Escaneig de comandes: Per escanejar tots els comentaris, executa la comanda Scan Wisemark Commands des de la paleta de comandes (Ctrl+Shift+P > Scan Wisemark commands).

   

3. Agrupar comentaris: Activa l’agrupament per a una millor visibilitat i organització dels teus comentaris utilitzant la comanda Toggle Grouping.

   

4. Navegar entre comentaris: Utilitza la comanda Select and Open a Comment per navegar ràpidament entre els comentaris del teu codi.

   

Configuració

Pots personalitzar els colors dels tokens per a cada tipus de comentari. Per defecte, Wisemark utilitza els següents colors:

• Nota: #ff6347 (cursiva)
• Todo: #e5c07b (negreta)
• FIXME: #f0f0f0 (cursiva)
• Refactorització: #00bcd4 (negreta)
• Pregunta: #8be9fd (cursiva)

Per personalitzar-ho, obre la configuració de VSCode i modifica "editor.tokenColorCustomizations" al teu gust.

Característiques predictives

Wisemark també prediu els comentaris més utilitzats segons el teu ús anterior, ajudant-te a agilitzar el procés.

Quick Pick per a comandes

Per a una inserció de comentaris encara més ràpida, utilitza la funcionalitat Quick Pick, que suggereix les millors opcions per a la teva tasca actual.

Agrupar comentaris per tipus

Agrupa fàcilment els teus comentaris per tipus per a una millor organització.

Full de ruta (Roadmap)

Contribucions

Si vols contribuir a Wisemark, no dubtis a enviar problemes (issues) i sol·licituds d’incorporació (pull requests). Les contribucions són benvingudes!

1. Fes un fork d’aquest repositori.
2. Crea la teva branca (git checkout -b feature/la-teva-funcionalitat).
3. Fes un commit dels teus canvis (git commit -am 'Afegir nova funcionalitat').
4. Puja a la branca (git push origin feature/la-teva-funcionalitat).
5. Obre una pull request.

Llicència

Aquest projecte està sota la llicència MIT - vegeu el fitxer LICENSE per a més detalls.

Gaudeix organitzant el teu codi i comentaris amb Wisemark!