@thaisdury/mdlinks

v1.0.0

Published

3 years ago

Library that extracts, validates and provides statistics from .md files

Downloads

0High
0Medium
0Low

thaisdury

markdown links

Markdown Links

Índice

1. Prefácio

Markdown é uma linguagem de marcação muito popular entre os programadores. É usada em muitas plataformas que manipulam texto (GitHub, fórum, blogs e etc) e é muito comum encontrar arquivos com este formato em qualquer repositório (começando pelo tradicional README.md).

Os arquivos Markdown normalmente contém links que podem estar quebrados, ou que já não são válidos, prejudicando muito o valor da informação que está ali.

Uma comunidade open source nos propôs criar uma ferramenta, usando Node.js, que leia e analise arquivos no formato Markdown, para verificar os arquivos que contenham links e mostrar algumas estatísticas.

md-links

2. Resumo do projeto

Node.js é um ambiente de execução para JavaScript construído com o motor de JavaScript V8 do Chrome. Ele vai nos permitir executar o JavaScript no nosso sistema operacional, seja no seu computador ou em um servidor, o que nos abre portas para poder interagir com sistemas, arquivos, redes e etc.

Neste projeto vamos ficar um pouco longe do navegador para construir um programa que seja executado com Node.js, onde iremos aprender sobre como interagir com sistemas de arquivos e com o ambiente onde é executado o Node (processo, env, stdin/stdout/stderr).

Neste projeto você criará uma ferramenta de linha de comando (CLI) assim como a sua própria biblioteca (library) em JavaScript.

3. Objetivos de aprendizagem

Desenvolver sua própria biblioteca é uma experiência fundamental para qualquer desenvolvedora, pois te obriga a pensar na interface (API) dos seus módulos e como ela será usada por outras desenvolvedoras. Você deve levar em conta as peculiaridades da linguagem, convenções e boas práticas.

A seguir você pode conferir os objetivos de aprendizagem deste projeto:

Javascript

[ ] Uso de condicionais (if-else | switch | operador ternario)
[ ] Uso de funções (parâmetros | argumentos | valor de retorno)
[ ] Manipular arrays (filter | map | sort | reduce)
[ ] Manipular objects (key | value)
[ ] Uso ES modules (import | export)
[ ] Diferença entre expression e statements.
[ ] Diferença entre tipos de dados atômicos e estruturados.
[ ] Uso de callbacks
[ ] Consumo de Promises
[ ] Criação de uma Promise

Node

[ ] Uso de sistema de arquivos (fs, path)
[ ] Instalar e usar módulos. (npm)
[ ] criação de módulos (CommonJS)
[ ] Configuração do package.json.
[ ] Configuração do npm-scripts
[ ] Uso de CLI (Command Line Interface - Interface de Linha de Comando)

Testing

[ ] Teste unitário.
[ ] Teste assíncrono.
[ ] Uso de bibliotecas de Mock.
[ ] Uso de Mocks manuais.
[ ] Teste para múltiplos Sistemas Operativos.

Estrutura do código e guia de estilo

[ ] Organizar e dividir o código em módulos (Modularização)
[ ] Uso de identificadores descritivos (Nomenclatura | Semântica)
[ ] Uso de linter (ESLINT)

Git e Github

[ ] Uso de comandos de git (add | commit | pull | status | push)
[ ] Gerenciamento de repositorios de GitHub (clone | fork | gh-pages)
[ ] Colaboração no Github (branches | pull requests | |tags)

HTTP

[ ] Verbos HTTP (http.get)

Fundamentos de programação

[ ] Recursão.

4. Considerações gerais

Este projeto deve ser feito individualmente.
A biblioteca e script executável (ferramenta de linha de comando - CLI) devem ser implementados em JavaScript para serem executadas com Node.JS. É permitido usar bibliotecas externas.
O seu módulo deve ser instalável via npm install <github-user>/md-links. O módulo deve incluir um executável que pode ser chamado tanto por linha de comando quanto importado com require para ser usado em seu código.
Os testes unitários devem cobrir no mínimo 70% dos statements, functions, lines e branches. Recomendamos que explore o Jest para as suas provas unitárias.
Neste projeto não é permitido utilizar async/await.
Para este projeto é opcional o uso de ES modules (import/export). Caso você decida utilizá-lo deverá criar um script de build no package.json para que seja transformado em requires e module.exports com ajuda do Babel.

5. Critérios de aceitação mínimos do projeto

Para começar este projeto você deverá fazer um fork e clonar este repositório.

Arquivos do projeto

README.md com descrição do módulo, instruções de instalação e uso, documentação da API e exemplos. Tudo que for relevante para qualquer desenvolvedora saber como utilizar a sua biblioteca sem inconvenientes.
index.js: este arquivo deve exportar a função mdLinks.
package.json deve possuir o nome, versão, descrição, autor, licença, dependências e scripts (pretest, test e etc).
.editorconfig com a configuração para o editor de texto. Este arquivo não deve ser alterado.
.eslintrc com a configuração para o linter. Este arquivo não deve ser alterado.
.gitignore para ignorar o node_modules e outras pastas que não devem ser incluídas no controle de versão (git).
test/md-links.spec.js deve conter os testes unitários para a função mdLinks(). A sua implementação deve rodar estes testes.

JavaScript API

O módulo deve poder ser importado em outros scripts Node.js e deve oferecer a seguinte interface:

`mdLinks(path, options)`

Argumentos

path: Rota absoluta ou relativa ao arquivo ou diretório. Se a rota passada é relativa, deve resolver como sendo relativa ao diretório onde foi chamada - current working directory
options: Um objeto com a seguinte propriedade:
- validate: Um booleano que determina se deseja validar os links encontrados.

Valor de retorno

A função deve retornar uma promessa (Promise) que resolve um array (Array) e objetos(Object), onde cada objeto representa um link, contendo as seguintes propriedades:

href: URL encontrada.
text: Texto que irá aparecer dentro de um link (<a>).
file: Rota do arquivo onde foi encontrado o link.

Exemplo

const mdLinks = require("md-links");

mdLinks("./some/example.md")
  .then(links => {
    // => [{ href, text, file }]
  })
  .catch(console.error);

mdLinks("./some/example.md", { validate: true })
  .then(links => {
    // => [{ href, text, file, status, ok }]
  })
  .catch(console.error);

mdLinks("./some/dir")
  .then(links => {
    // => [{ href, text, file }]
  })
  .catch(console.error);

CLI (Command Line Interface - Interface de Linha de Comando)

O executável da nossa aplicação deve poder ser executado da seguinte maneira, através do terminal:

md-links <path-to-file> [options]

Por exemplo:

$ md-links ./some/example.md
./some/example.md http://algo.com/2/3/ Link de algo
./some/example.md https://outra-coisa-.net/algum-doc.html algum doc
./some/example.md http://google.com/ Google

O comportamento padrão não deve validar se as URLs respondem ok ou não, somente deve identificar o arquivo Markdown (a partir da rota que recebeu como argumento), analisar o arquivo Markdown e imprimir os links que vão sendo encontrados, junto com a rota do arquivo onde aparece e o texto encontrado dentro do link (truncado 50 caracteres).

Options

`--validate`

Se passamos a opção --validate, o módulo deve fazer uma requisição HTTP para verificar se o link funciona ou não. Se o link resultar em um redirecionamento a uma URL que responde ok, então consideraremos o link como ok.

Por exemplo:

$ md-links ./some/example.md --validate
./some/example.md http://algo.com/2/3/ ok 200 Link de algo
./some/example.md https://outra-coisa-.net/algum-doc.html fail 404 algum doc
./some/example.md http://google.com/ ok 301 Google

Vemos que o output neste caso inclui a palavra ok e fail depois da URL, assim como o status da resposta recebida à requisição HTTP feita pela URL.

`--stats`

Se passamos a opção --stats o output (saída) será um texto com estatísticas básicas sobre os links.

$ md-links ./some/example.md --stats
Total: 3
Unique: 3

Também podemos combinar --stats e --validate para obter estatísticas que necessitem dos resultados da validação.

$ md-links ./some/example.md --stats --validate
Total: 3
Unique: 3
Broken: 1

6. Entregáveis

O módulo deve ser instalável via npm install <github-user>/md-links. Este módulo deve incluir um executável que pode ser chamado tanto por linha de comando quanto importado com require para usá-lo no seu código.

7. Hacker edition

As seções chamadas Hacker Edition são opcionais. É para caso você tenha terminado todos os requisitos anteriores e ainda tenha tempo disponível, e pode assim aprofundar e/ou exercitar mais sobre os objetivos de aprendizagem deste projeto.

Poder adicionar uma propriedade line a cada objeto link indicando em que linha do arquivo está o link.
Poder agregar mais estatísticas.

8. Guias, dicas e leituras complementares

FAQs

Como faço para que o meu módulo seja instalável pelo GitHub?

Para que o módulo seja instalável pelo GitHub você tem que:

Deixar o seu repo público
Ter um package.json válido

Com o comando npm install <githubname>/<reponame> podemos instalar diretamente pelo GitHub. Ver docs oficiais dp npm install aqui

Por exemplo, o course-parser que é usado para o currículo não está publicado nos registros públicos do NPM, com isso temos que instalar diretamente pelo GitHub com o commando npm install Laboratoria/course-parser.

Sugestões de implementação

A implementação deste projeto tem várias partes: ler do sistema de arquivos, receber argumentos através da linha de comando, analisar um teste, fazer consultas HTTP, etc. Tudo isso pode ser feito de muitas formas, tanto com bibliotecas quanto com JS puro.

Por exemplo, o parse (análise) do Markdown para extrair os links poderia ser criado das seguintes maneiras (todas são válidas):

Usando um módulo como markdown-it, que nos devolve um array de tokes que utilizamos para identificar os links.
Seguindo outro caminho, poderíamos usar expressões regulares (RegExp).
Também poderíamos usar uma combinação de vários módulos (poderia ser válido transformar o markdown em um HTML usando o marked e depois extrair os links com uma biblioteca de DOM como JSDOM o Cheerio).
Usando um custom renderer de marked (new marked.Renderer()).

Nós recomendamos o uso de Regex ou da biblioteca de JSDOM

Não hesite em consultar as suas companheiras, mentores e/ou o fórum da comunidade se tiver dúvidas a respeito destas decisões. Não existe uma única maneira certa :wink:

Tutoriais / NodeSchool workshoppers

Outros recursos

9. Checklist

General

[ ] Poder instalar via npm install --global <github-user>/md-links

`README.md`

[ ] Um board com o backlog das implementações da sua biblioteca
[ ] Documentação técnica da sua biblioteca
[ ] Guia de uso e instalação da biblioteca

API `mdLinks(path, opts)`

[ ] O módulo exporta uma função com a interface (API) esperada
[ ] Implementa suporte para arquivo individual
[ ] Implementa suporte para diretórios
[ ] Implementa options.validate

CLI

[ ] Possuir o executável md-links no path (configurado no package.json)
[ ] Executar sem erros e ter o resultado esperado
[ ] Implementar --validate
[ ] Implementar --stats

Testes

[ ] Os testes unitários devem cobrir no mínimo 70% dos statements, functions, lines e branches.
[ ] Rodar os testes e linter (npm test).