/SAP007-md-links

Primary LanguageJavaScript

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

Neste projeto, será criado uma ferramenta de linha de comando (CLI) assim como a sua própria biblioteca (library) em Javascript.

Desta vez, vamos ficar um pouco longe do navegador para construir um programa executado com Node.js. Iremos aprender sobre processos (process.env, process.argv, ...),como interagir com sistemas de arquivos, como fazer consultas de rede, etc.

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.

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.

3. Objetivos de aprendizagem

Reflita e depois enumere os objetivos que quer alcançar e aplique no seu projeto. Pense nisso para decidir sua estratégia de trabalho.

JavaScript

  • Teste de compatibilidade em vários ambientes de tempo de execução

  • Uso de linter (ESLINT)

  • Uso de identificadores descritivos (Nomenclatura | Semântica)

Node.js

Controle de Versões (Git e GitHub)

  • Git: Instalação e configuração

  • Git: Controle de versão com git (init, clone, add, commit, status, push, pull, remote)

  • Git: Integração de mudanças entre ramos (branch, checkout, fetch, merge, reset, rebase, tag)

  • GitHub: Criação de contas e repositórios, configuração de chave SSH

  • GitHub: Implantação com GitHub Pages

    Links

  • GitHub: Colaboração pelo Github (branches | forks | pull requests | code review | tags)

  • GitHub: Organização pelo Github (projects | issues | labels | milestones | releases)

HTTP

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.

Antes de começar o código, é necessário criar um plano de ação. Ele deve estar detalhado no README.md do seu repositório e em uma série de issues e milestones para priorizar e organizar o trabalho, e para fazer um acompanhamento do seu progresso.

Dentro de cada milestone serão criados e atribuidos as issues que considerar necessários.

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 contém uma configuração básica para ESLint, se quiser colocar regras adicionais como Airbnb, você deverá modificar este arquivo.
  • .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.

Este proyecto consta de DOS partes

1) 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.
    • stats: Booleano que determina se deseja obter um output com informações estatísticas gerais.
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:

Com validate:false :

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

Com validate:true :

  • href: URL encontrada.
  • text: Texto que aparecía dentro del link (<a>).
  • file: Ruta del archivo donde se encontró el link.
  • status: Código de resposta HTTP.
  • ok: Mensagem fail em caso de falha ou ok em caso de sucesso.

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);

2) 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, como também possa ser 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.
  • Integração contínua com Travis ou Circle CI.

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ão hesite em consultar as suas companheiras e mentores se tiver dúvidas a respeito destas decisões. Não existe uma única maneira certa 😉

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

10. Dividindo o problema

Uma das habilidades que esperamos que vocˆw possa desenvolver durante o bootcamp é o de definir "mini-projetos/babies steps" que a aproxime passo-a-passo da solução do "grande projeto". É o mesmo que começar fazendo as bordas de um quebra-cabeça sem necessariamente saber como se encaixará no final.

Estas são algumas sugestões:

Comece com um fluxograma

Este projeto é diferente dos que você tem trabalhado até agora. Como não há uma interface web, tudo será desenvolvido em seu editor e consola/terminal.

Por isso, para visualizar melhor o que você terá que fazer para planejar suas tarefas e objetivos, é aconselhável fazer um fluxograma.

Se você nunca fez um fluxograma, confira este recurso.

Uma alternativa ao fluxograma pode ser pseudocódigo.

Planejamento

Neste projeto recomendamos o uso do Github Projects, ferramenta de planejamento e organização do GitHub

Por meio de issues e milestones pode-se organizar e planificar tarefas e objetivos concretos.

Levando em consideração os entregáveis do projeto, 9. Checklist e os passos que foram definidos em seu fluxograma, crie o seu planejamento em GitHub Projects.

Antes do código

Desta vez você estará trabalhando em NodeJS, certifique-se de saber para que serve e suas considerações.

Em particular, é preciso decidir antecipadamente se usará ES Modules, ou seja usar import/export, ou se utilizará CommonJS Modules, ou seja require/module.exports.

Certifique-se de ter esta decisão clara desde o início para que você não encontre problemas mais tarde.

Ler um arquivo

Como primeiro desafio, você pode tentar ler um único arquivo com um caminho fixo e imprimir seu conteúdo no console com um console.log.

A biblioteca nativa FS (FileSystem) será útil para você.

Descobrir a extensão de um arquivo

Já sabendo ler um arquivo, aventure-se em saber qual é a sua extensão.

Lembre-se, as extensões são aquelas letras no final do nome de um arquivo, por exemplo: .js, .txt, .doc etc.

A biblioteca FS também pode ser útil aqui.

Obter o conteúdo de um diretório

Este projeto consiste em buscar arquivos, mas para isso, você deve primeiro ser capaz de vê-los.

Tenta imprimir para console a lista de arquivos em uma pasta.

A biblioteca FS também será útil aqui.

Definir rotas

Para acessar pastas e arquivos, será necessário indicar onde eles estão localizados em seu computador, sendo chamadas de rotas.

Use a biblioteca nativa path para unir dois segmentos de caminho, Por exemplo, se quisermos juntar:

  1. /home/Laboratório/
  2. ./teste

O resultado seria: /home/Lab/test

Recursão

Este projeto pode ser resolvido com recursão.

Por que?

Porque não sabemos quantas pastas e arquivos teremos que passar antes de terminar.

Se você receber um caminho de pasta, não saberá com antecedência se há mais pastas dentro ou mais arquivos.

Portanto, certifique-se de entender o que o recursão e veja alguns exemplos.

Crie uma promessa

O valor de retorno da nossa biblioteca é uma Promise, não um Array.

Tente ler sobre promessas e criando uma por conta própria usando new Promise()

É importante que você saiba o que é um callback porque serão usadas nas promessas.