• 1. Preámbulo
• 2. Plan de acción
• 3. Objetivos de aprendizaje de este proyecto
• 4. Checklist de entregables
• 5. Instrucciones de instalación de la librería
• 6. Instrucciones de uso desde la línea de comandos
• 7. Instrucciones de uso para importar con require

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.

• Investigar sobre node.js (NodeSchool workshopper learnyounode).

• Definir diferentes comandos de entrada posibles para mi programa.
• Hacer diagrama de flujo.
• Realizar función para verificar si la ruta ingresada existe y comprobar si es archivo o directorio.
• Utilizar file system (Fs) para leer un archivo o directorio, según sea el caso.
• Verificar que el o los archivos tengan extensión .md
• Investigar como poder extraer los links del archivo markdown.

• Probar módulo markdown-it.
• Convertir archivo markdown a Html con propiedad render de markdown-it.
• Simular un DOM con el html generado por markdown-it, utilizando la libreria JSDOM, y así poder usar la propiedad windows de ese DOM para acceder window.querySelectorAll para extraer todos los links del archivo.
• Generar un array que contenga un objeto con las propiedades href, text y file por cada uno de los links encontrados.
• Investigar sobre librerias para hacer solicitudes HTTP.
• Investigar sobre el método get de Node.js
• Hacer condicional para definir cuales links usan protocolo http y cuales https y emplear el método get para hacer las solcitudes correspondientes.
• Agregar las propiedades status y ok a los objetos de los links.

• Refactorizar y pasar todo el código a promesas
• Crear módulo (exportar función mdLinks).
• Crear archivo cli.js y requerir el módulo mdLinks.
• Consumir la promesa que devuelve el módulo mdLinks.
• Crear función con cuatro condicionales de acuerdo a las posibles entradas que se pueden tener.

• Hacer conteo de total de links, links rotos y links unicos.
• Realizar test unitarios y asíncronos de las funciones en mdLinks.js.
• Manejo de errores que faltaban.
• Documentación y README.

• Uso de condicionales (if-else | switch | operador ternario)
• Uso de funciones (parámetros | argumentos | valor de retorno)
• Manipular arrays (filter | map | sort | reduce)
• Manipular objects (key | value)
• Uso ES modules (import | export)
• Diferenciar entre expression y statements.
• Diferenciar entre tipos de datos atómicos y estructurados.
• Uso de callbacks.
• Consumo de Promesas.
• Creación de Promesas.

• Uso de sistema de archivos. (fs, path)
• Instalar y usar módulos. (npm)
• Creación de modules. (CommonJS)
• Configuración de package.json.
• Configuración de npm-scripts
• Uso de CLI (Command Line Interface - Interfaz de Línea de Comando)

• Testeo unitario.
• Testeo asíncrono.
• Uso de librerias de Mock.
• Uso de Mocks manuales.
• Testeo para múltiples Sistemas Operativos.

• Organizar y dividir el código en módulos (Modularización)
• Uso de identificadores descriptivos (Nomenclatura | Semántica)
• Uso de linter (ESLINT)

• Uso de comandos de git (add | commit | pull | status | push)
• Manejo de repositorios de GitHub (clone | fork | gh-pages)
• Colaboración en Github (branches | pull requests | |tags)
• Organización en Github (projects | issues | labels | milestones)

• Verbos HTTP (http.get)

• Recursión.

• Puede instalarse via npm install --global <github-user>/md-links

• 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 options.validate

• Expone ejecutable md-links en el path (configurado en package.json)
• Se ejecuta sin errores / output esperado
• Implementa --validate
• Implementa --stats

• Pruebas unitarias cubren un mínimo del 70% de statements, functions, lines, y branches.
• Pasa tests (y linters) (npm test).

Para instalar el módulo debes escribir en la terminal:

              npm install CamiYanez/bog001-md-links

Luego de instalarlo puedes ejecutar el programa de la siguiente manera a través de la terminal:

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

O puedes usarlo con require desde tu archivo js de la siguiente manera:

              const { mdLinks } = require('@CamiYanez/mdLinks')

Tienes cuatro posibles opciones de respuesta de acuerdo al comando que ejecutes a través de tu terminal, la estructura del comando debe ser md-links <path> [options] donde path es la ruta al archivo o directorio, y options puede ser --validate y/o --stats (este parámetro es opcional).

Por ejemplo: $ md-links ./some/example.md

En caso de no especificar options la salida será un array de objetos donde cada objeto correspondera a un link con las siguientes propiedades:

• href: URL encontrada.
• text: Texto que aparecía dentro del link (<a>).
• file: Ruta del archivo donde se encontró el link.

Por ejemplo: $ md-links ./some/example.md --validate

En caso de especificar unicamente la opción validate la salida será un array de objetos donde cada objeto correspondera a un link con las siguientes propiedades:

• 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 estado de respuesta de la petición HTTP a la URL encontrada.
• ok: Depende del status, será ok si la petición fue exitosa y fail si hubo algún problema.

Por ejemplo: $ md-links ./some/example.md --stats

En caso de especificar unicamente la opción stats la salida será la estadistica del total de links encontrados y la cantidad de links unicos encontrados.

Total Links: 3
Unique Links: 3

Por ejemplo: $ md-links ./some/example.md --validate --stats

En caso de especificar ambas opciones la salida será el total de links, links unicos, y links rotos encontrados.

Total Links: 3
Unique Links: 3
Broken Links: 1

Para usar el módulo dentro de tu código puedes importarlo de la siguiente manera: const { mdLinks } = require('./mdLinks')

mdLinks es una función que recibe dos parametros mdLinks(path, option) donde path es la ruta al archivo o directorio y option es un objeto con una propiedad llamada validate que debe contener un Booleano que sea true si deseas validar los links encontrados o false si no.

Esta función retorna una promesa que resuelve un array de objetos, cada objeto representa un link, y las propiedades de estos objetos varian de acuerdo al parametro options, si es false tendrá las propiedades href, text y file, pero si es true tendrá las propiedades href, text, file, status y ok, donde:

• 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 estado de respuesta de la petición HTTP a la URL encontrada.
• ok: Depende del status, será ok si la petición fue exitosa y fail si hubo algún problema.

mdLinks(path, option)
    .then(links => {
        console.log(links)
    });

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

links es el array de objetos que mencionabamos anteriormente, ya puedes usar esta data para lo que necesites.