- 1. Pre谩mbulo
- 2. Resumen del proyecto
- 3. Objetivos de aprendizaje
- 4. Consideraciones generales
- 5. Criterios de aceptaci贸n del proyecto
- 6. Entregables
- 7. Hacker edition
- 8. Pistas y lecturas complementarias
- 9. Checklist
***聽
Markdown es un lenguaje de marcado
ligero muy popular entre developers. Es usado en much铆simas plataformas que
manejan texto plano (GitHub, foros, blogs, ...), y es muy com煤n
encontrar varios archivos en ese formato en cualquier tipo de repositorio
(empezando por el tradicional README.md
).
Estos archivos Markdown
normalmente contienen links (v铆nculos/ligas) que
muchas veces est谩n rotos o ya no son v谩lidos y eso perjudica mucho el valor de
la informaci贸n que se quiere compartir.
Dentro de una comunidad de c贸digo abierto, nos han propuesto crear una
herramienta usando Node.js, que lea y analice archivos
en formato Markdown
, para verificar los links que contengan y reportar
algunas estad铆sticas.
Node.js es un entorno de ejecuci贸n para JavaScript construido con el motor de JavaScript V8 de Chrome. Esto nos va a permitir ejecutar JavaScript en el entorno del sistema operativo, ya sea tu m谩quina o un servidor, lo cual nos abre las puertas para poder interactuar con el sistema en s铆, archivos, redes, ...
En este proyecto nos alejamos un poco del navegador para construir un programa que se ejecute usando Node.js, donde aprenderemos sobre c贸mo interactuar con el sistema archivos, con el entorno (proceso, env, stdin/stdout/stderr), ...
El objetivo pr谩ctico de este proyecto es que aprendas c贸mo crear tu propia librer铆a (o biblioteca - library) en JavaScript.
Dise帽ar tu propia librer铆a es una experiencia fundamental para cualquier desarrollador porque que te obliga a pensar en la interfaz (API) de tus m贸dulos y c贸mo ser谩 usado por otros developers. Debes tener especial consideraci贸n en peculiaridades del lenguaje, convenciones y buenas pr谩cticas.
T贸picos:
- Node.js.
- m贸dulos (CommonJS).
- file system.
- path.
- http.get.
- Parsing.
- markdown.
- CLI.
- npm-scripts.
- semver.
Durante el desarrollo del proyecto implementaras conocimientos que fueron adquiridos en los proyectos anteriores; Lo cual este proyecto nos permitir谩 reforzar esos conocimientos anteriores; Pero tambi茅n aprenderemos nuevos temas que nos serviran en nuestro desarrollo de developers, c贸mo los temas encontrados en la secci贸n anterior; Pero alguno temas que nos facilitara el desarrollo del proyecto como son:
- Saber que es Node.js
- CLI
- File system/paths
- Promesas
- Loops
Este proyecto se debe "resolver" de manera individual.
La librer铆a debe estar implementada en JavaScript para ser ejecutada con Node.js. Est谩 permitido usar librer铆as externas.
Tu m贸dulo debe ser instalable via npm install <github-user>/md-links
. Este
m贸dulo debe incluir tanto un ejecutable que podamos invocar en la l铆nea de
comando como una interfaz que podamos importar con require
para usarlo
program谩ticamente.
Los tests unitarios deben cubrir statements, functions, lines y branches. Te recomendamos explorar Jest para tus pruebas unitarias; As铆 como agregar la configuraci贸n de coverage para tus test.
Para comenzar este proyecto tendr谩s que hacer un fork y clonar este repositorio.
Antes de comenzar a codear, es necesario crear un plan de acci贸n. Esto deber铆a
quedar detallado en el README.md
de tu repo y en una serie de issues
y milestones para priorizar y organizar el trabajo, y para poder hacer
seguimiento de tu progreso.
Dentro de cada milestone se crear谩n y asignar谩n los issues que cada quien considere necesarios.
El proyecto debera de contener los siguientes archivos base de configuraci贸n, aunque no seran los unicos archivos que quiz谩s tendras que crear.
README.md
con descripci贸n del m贸dulo, instrucciones de instalaci贸n/uso, documentaci贸n del API y ejemplos. Todo lo relevante para que cualquier developer que quiera usar tu librer铆a pueda hacerlo sin inconvenientes.index.js
: Desde este archivo debes exportar una funci贸n (mdLinks
).package.json
con nombre, versi贸n, descripci贸n, autores, licencia, dependencias, scripts (pretest, test, ...).editorconfig
con configuraci贸n para editores de texto. Este archivo no se debe cambiar..eslintrc
con configuraci贸n para linter. Este archivo no se debe cambiar..gitignore
para ignorarnode_modules
u otras carpetas que no deban incluirse en control de versiones (git
).test/md-links.spec.js
debe contener los tests unitarios para la funci贸nmdLinks()
. Tu inplementaci贸n debe pasar estos tets.
El m贸dulo debe poder importarse en otros scripts de Node.js y debe ofrecer la siguiente interfaz:
path
: Ruta absoluta o relativa al archivo o directorio. Si la ruta pasada es relativa, debe resolverse como relativa al directorio desde donde se invoca node - current working directory).options
: Un objeto con las siguientes propiedades:validate
: Booleano que determina si se desea validar los links encontrados.
La funci贸n debe retornar una promesa (Promise
) que resuelva a un arreglo
(Array
) de objetos (Object
), donde cada objeto representa un link y contiene
las siguientes propiedades:
href
: URL encontrada.text
: Texto que aparec铆a dentro del link (<a>
).file
: Ruta del archivo donde se encontr贸 el link.
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);
El ejecutable de nuestra aplicaci贸n debe poder ejecutarse de la siguiente manera a trav茅s de la terminal:
md-links <path-to-file> [options]
Por ejemplo:
$ md-links ./some/example.md
./some/example.md http://algo.com/2/3/ Link a algo
./some/example.md https://otra-cosa.net/algun-doc.html alg煤n doc
./some/example.md http://google.com/ Google
El comportamiento por defecto no debe validar si las URLs responden ok o no, solo debe identificar el archivo markdown (a partir de la ruta que recibe como argumento), analizar el archivo Markdown e imprimir los links que vaya encontrando, junto con la ruta del archivo donde aparece y el texto que hay dentro del link (truncado a 50 caracteres).
Si pasamos la opci贸n --validate
, el m贸dulo debe hacer una petici贸n HTTP para
averiguar si el link funciona o no. Si el link resulta en una redirecci贸n a una
URL que responde ok, entonces consideraremos el link como ok.
Por ejemplo:
$ md-links ./some/example.md --validate
./some/example.md http://algo.com/2/3/ ok 200 Link a algo
./some/example.md https://otra-cosa.net/algun-doc.html fail 404 alg煤n doc
./some/example.md http://google.com/ ok 301 Google
Vemos que el output en este caso incluye la palabra ok
o fail
despu茅s de
la URL, as铆 como el status de la respuesta recibida a la petici贸n HTTP a dicha
URL.
Si pasamos la opci贸n --stats
el output (salida) ser谩 un texto con estad铆sticas
b谩sicas sobre los links.
$ md-links ./some/example.md --stats
Total: 3
Unique: 3
Tambi茅n podemos combinar --stats
y --validate
para obtener estad铆sticas que
necesiten de los resultados de la validaci贸n.
$ md-links ./some/example.md --stats --validate
Total: 3
Unique: 3
Broken: 1
- Pseudo codigo o diagrama de flujo con el algoritmo que soluciona el problema.
- M贸dulo instalable via
npm install <github-user>/md-links
. Este m贸dulo debe incluir tanto un ejecutable como una interfaz que podamos importar conrequire
para usarlo program谩ticamente.
Antes de empezar a resolver estos puntos es importante que hayas terminado con lo presentado anteriormente.
- Puedes agregar la propiedad
line
a cada objetolink
indicando en qu茅 l铆nea del archivo se encontr贸 el link. - Puedes agregar m谩s estad铆sticas.
- Integraci贸n continua con Travis o Circle CI.
Para que el m贸dulo sea instalable desde GitHub solo tiene que:
- Estar en un repo p煤blico de GitHub
- Contener un
package.json
v谩lido
Con el comando npm install githubname/reponame
podemos instalar directamente
desde GitHub. Ver docs oficiales de npm install
ac谩.
Por ejemplo, el course-parser
que usamos para la curr铆cula no est谩 publicado en el registro p煤blico de NPM,
as铆 que lo instalamos directamente desde GitHub con el comando npm install Laboratoria/course-parser
.
La implementaci贸n de este proyecto tiene varias partes: leer del sistema de archivos, recibir argumentos a trav茅s de la l铆nea de comando, analizar texto, hacer consultas HTTP, ... y todas estas cosas pueden enfocarse de muchas formas, tanto usando librer铆as como implementando en VanillaJS.
Por poner un ejemplo, el parseado (an谩lisis) del markdown para extraer los links podr铆a plantearse de las siguientes maneras (todas v谩lidas):
- Usando un m贸dulo como markdown-it, que nos devuelve un arreglo de tokens que podemos recorrer para identificar los links.
- Siguiendo otro camino completamente, podr铆amos usar
expresiones regulares (
RegExp
). - Tambi茅n podr铆amos usar una combinaci贸n de varios m贸dulos (podr铆a ser v谩lido transformar el markdown a HTML usando algo como marked y de ah铆 extraer los link con una librer铆a de DOM como JSDOM o Cheerio entre otras).
- Usando un custom renderer de marked
(
new marked.Renderer()
).
No dudes en consultar a tus compa帽eras, coaches y/o el foro de la comunidad si tienes dudas existenciales con respecto a estas decisiones. No existe una "煤nica" manera correcta 馃槈
- Acerca de Node.js - Documentaci贸n oficial
- Node.js file system - Documentaci贸n oficial
- Node.js http.get - Documentaci贸n oficial
- Node.js - Wikipedia
- What exactly is Node.js? - freeCodeCamp
- 驴Qu茅 es Node.js y para qu茅 sirve? - drauta.com
- 驴Qu茅 es Nodejs? Javascript en el Servidor - Fazt en YouTube
- 驴Simplemente qu茅 es Node.js? - IBM Developer Works, 2011
- Node.js y npm
- M贸dulos, librer铆as, paquetes, frameworks... 驴cu谩l es la diferencia?
- As铆ncron铆a en js
- NPM
- Publicar packpage
- Crear m贸dulos en Node.js
- Leer un archivo
- Leer un directorio
- Path
- Linea de comando CLI
- Puede instalarse via
npm install --global <github-user>/md-links
- Pseudo codigo o diagrama de flujo con el algoritmo que soluciona el problema.
- Un board con el backlog para la implementaci贸n de la librer铆a.
- Documentaci贸n t茅cnica de la librer铆a.
- Gu铆a de uso e instalaci贸n de la librer铆a
- El m贸dulo exporta una funci贸n con la interfaz (API) esperada.
- Implementa soporte para archivo individual
- Implementa soporte para directorios
- Implementa
opts.validate
- Expone ejecutable
md-links
en el path (configurado enpackage.json
) - Se ejecuta sin errores / output esperado
- Implementa
--validate
- Implementa
--stats
- El ejecutable implementa
--validate
y--stats
juntos.
- Pruebas unitarias cubren un m铆nimo del 70% de statements, functions, lines, y branches.
- Pasa tests (y linters) (
npm test
).