Markdown Links

Índice

• 1. Prefácio
• 2. Resumo do projeto
• 3. Recursos Principais
• 4. Guia Prático de Instalação e Uso
• 5. Testes Unitários
• 6. Critérios Minímos de Aceitação
• 7. Especificações Técnicas
• 8. Implementações futuras
• 9. Desenvolvedora

1. Prefácio

Markdown é uma linguagem de marcação amplamente adotada pela comunidade de programadores. Ela encontra aplicação em diversas plataformas de edição e formatação de texto, incluindo o GitHub, fóruns, e blogs. Arquivos formatados em Markdown são uma presença comum em qualquer repositório, sendo o README.md o exemplo mais representativo.

Esses documentos em Markdown costumam conter links que podem estar quebrados, ou que já não são válidos, o que prejudica consideravelmente o valor da informação presente.

Este projeto foi desenvolvido como parte do bootcamp da Laboratória e consiste em um projeto de nível 4 de um catálogo de projetos de complexidade crescente, associados a objetivos de aprendizagem concretos. Portanto, Este projeto tem como objetivo desenvolver uma biblioteca JavaScript e uma ferramenta de linha de comando (CLI) para ler e analisar arquivos Markdown. Utilizando o ambiente Node.js, a biblioteca verificará os links presentes nos arquivos Markdown, extraindo e validando esses links fornecendo estatísticas relevantes.

2. Resumo do projeto

Md-links é uma biblioteca JavaScript que simplifica a extração de links de arquivos Markdown, facilitando a validação de links e fornecimento de estatísticas úteis. Ele é facilmente instalável via npm, tornando-se acessível aos desenvolvedores.

Principais Características:

• Extração de Links: Md-links verifica eficientemente arquivos Markdown e extrai todos os links, economizando tempo em comparação com a extração manual.
• Validação de Links: Além da extração, valida os links para garantir que estejam ativos.
• Estatísticas Detalhadas: Fornece estatísticas abrangentes sobre os links encontrados nos arquivos.

Desenvolvimento do Projeto:

Neste projeto, adquirimos conhecimentos essenciais em programação com Node.js, incluindo o entendimento de processos, interação com sistemas de arquivos, e a realização de consultas de rede. Também exploramos o potencial do Node.js como ambiente de execução JavaScript e desenvolvemos habilidades em criar bibliotecas com uma ênfase na criação de interfaces de módulos eficazes e aderência a boas práticas de desenvolvimento.

Fluxograma

o fluxograma é uma ferramenta essencial que nos ajuda a planejar, acompanhar e alcançar os marcos do projeto de forma organizada e eficaz, tornando mais tangíveis os objetivos de aprendizagem estabelecidos. Dessa forma, o uso do fluxograma desempenhou um papel fundamental na estruturação e alcance dos objetivos de aprendizagem deste projeto. Ele atuou como um guia visual que nos ajudou a quebrar o projeto em pequenos passos, identificando as etapas principais do projeto. Com a ajuda do fluxograma, podemos visualizar a progressão e a conexão entre tarefas, tornando o processo de aprendizagem mais claro e gerenciável, refletindo as mudanças e ajustes necessários.

Fluxograma MD-Links

3. Recursos Principais

Leitura de Arquivos Markdown:

• O programa recebe como entrada arquivos no formato Markdown (.md) a partir da linha de comando.

Extração de Links:

• Extrai todos os links (URLs) presentes nos arquivos Markdown fornecidos como entrada.

Validação dos Links:

• Opção --validate que verifica o status HTTP de cada link extraído e exibe o HTTP status code associado a cada um.

Estatísticas de Links:

• Opção --stats para fornecer estatísticas sobre os links presentes nos arquivos, incluindo o total de links e a contagem de links únicos (sem duplicatas).

Combinação de Validação e Estatísticas:

• Opções --validate e --stats em conjunto, ao usar essa opção o programa gera estatísticas detalhadas, incluindo o número de links quebrados, encontrados durante a validação, o total de links e a contagem de links únicos (sem duplicatas) dos dados estatísticos.

Mensagens de Erro:

• Implementação de mensagens de erro para lidar com os erros de entrada ou opções inválidas.

4. Guia Prático de Instalação e Uso

4.1. Instalação

Para instalação da biblioteca execute o seguinte comando através do terminal:

npm install md-links-jayanny-santana

4.2. Uso

A ferramenta MD-Links oference os seguintes recursos para arquivo Markdown ('.md'), e que podem ser executados a partir do terminal:

Extração dos links

Para leitura e extração dos links de um arquivo Markdown ('.md'), execute o seguinte comando:

md-links <caminho-do-arquivo>

Validação de links

Para validar os links de um arquivo Markdown ('.md'), execute o seguinte comando:

md-links <caminho-do-arquivo> --validate

Estatísticas de links

Para gerar dados estatísticos de um arquivo Markdown ('.md'), execute o seguinte comando:

md-links <caminho-do-arquivo> --stats

Validação e Estatísticas de links

Para validar os links e gerar dados estatísticas de um arquivo Markdown ('.md'), execute o seguinte comando:

md-links <caminho-do-arquivo> --validate --stats

Mensagens de erro

A ferramenta é capaz de lidar com erros, por exemplo, mensagens de erro podem ser geradas em situações como estas:

• Quando a extensão do arquivo não for Markdown ('.md')

• Quando o arquivo Markdown ('.md') não puder ser lido:

• Quando o arquivo Markdown ('.md') estiver vazio e não possuir links no seu conteúdo:

• Quando a validação dos links do arquivo Markdown ('.md') falhar:

• Quando a estatística dos links do arquivo Markdown ('.md') falhar:

• Quando a validação e estatística dos links do arquivo Markdown ('.md') falhar:

5. Testes Unitários

Para este projeto foram desenvolvidos testes unitários utilizando a biblioteca de testes Jest. Dessa forma, os testes contemplaram as funções encarregadas ler, extrair, validar e gerar dados estatísticos dos links em arquivos Markdown ('.md'), assim como tratar as opções dados referentes aos links.

Os testes unitários realizados obtiveram uma cobertura de 100% de statements (sentenças), functions (funções), lines (linhas), e branches (ramos) dos arquivos index.js e md-links.js.

6. Critérios Minímos de Aceitação

• [x] Poder instalar via npm install
• [x] Guia de uso e instalação da biblioteca
• [x] Implementa suporte para arquivo individual
• [x] Implementa options.validate
• [x] Possuir o executável md-links no path (configurado no package.json)
• [x] Implementar --validate
• [x] Implementar --stats
• [x] Implementar --validate --stats
• [x] Os testes unitários devem cobrir no mínimo 70% dos statements, functions, lines e branches
• [x] Rodar os testes e linter (npm test).

7. Especificações Técnicas

O projeto foi desenvolvido utilizando como ferramentas e tecnologias:

• JavaScript
• Node.js
• Npm.js
• Chalk
• Jest
• GitHub
• Git Bash
• Whimsical

8. Implementações futuras

• Implementar suporte para diretórios
• Poder adicionar uma propriedade line a cada objeto link indicando em que linha do arquivo está o link
• Poder agregar mais estatísticas
• Integração contínua com Travis ou Circle CI.

9. Desenvolvedora

Jayanny Santana

• GitHub: @jay-santana
• Linkedin: Jayanny Santana