0.1.0 • Published 11 months ago

mdlinks-irmaginary v0.1.0

Weekly downloads
-
License
ISC
Repository
github
Last release
11 months ago

Markdown Links

Índice

1. Preámbulo

Markdown es un lenguaje de marcado ligero muy popular entre developers. Es usado en muchísimas plataformas que manejan texto plano (GitHub, foros, blogs, etc.) 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.

md-links

2. Resumen del proyecto

En este proyecto desarrollarás una librería en Node.js que funcionará como herramienta para analizar links dentro de archivos Markdown. Esta librería estará disponible de dos formas: como un módulo publicado en GitHub, que las usuarias podrán instalar e importar en otros proyectos, y como una interfaz de línea de comandos (CLI) que permitirá utilizar la librería directamente desde el terminal.

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, etc.

En esta oportunidad nos alejamos un poco del navegador para construir una librería que interactua con el sistema archivos y un script que se ejecute usando Node.js. Aprenderemos cómo buscar y leer archivos, cómo hacer consultas de red, sobre procesos (process.env, process.argv, ...), etc.

Diseñar tu propia librería es una experiencia fundamental para cualquier desarrolladora porque que te obliga a pensar en la interfaz (API) de tus módulos y cómo será usado por otras developers. Debes tener especial consideración en peculiaridades del lenguaje, convenciones y buenas prácticas. Al finalizar, podrás instalar esta librería utilizando NPM (Node Package Manager), que facilita la búsqueda e instalación de librerías de Node a través de su registro y también de GitHub. Una vez que hayas subido la librería a tu repositorio público, será accesible para otras developers.

3. Objetivos de aprendizaje

Reflexiona y luego marca los objetivos que has llegado a entender y aplicar en tu proyecto. Piensa en eso al decidir tu estrategia de trabajo.

JavaScript

Node.js

Control de Versiones (Git y GitHub)

  • Git: Instalación y configuración

  • Git: Control de versiones con git (init, clone, add, commit, status, push, pull, remote)

  • Git: Integración de cambios entre ramas (branch, checkout, fetch, merge, reset, rebase, tag)

  • GitHub: Creación de cuenta y repos, configuración de llaves SSH

  • GitHub: Colaboración en Github (branches | forks | pull requests | code review | tags)

  • GitHub: Organización en Github (projects | issues | labels | milestones | releases)

HTTP

4. Consideraciones generales

  • Este proyecto se debe "resolver" de manera individual.

  • El rango de tiempo estimado para completar el proyecto es de 3 a 5 sprints.

  • Consideramos los hitos 1 y 2 como los criterios de aceptación mínimos del proyecto.

  • Enfócate en aprender y no solamente en "completar" todos los hitos del proyecto.

  • Te sugerimos que no intentes saber todo de Node.js antes de empezar a codear. No es necesario tomar un curso de Node.js completo. Aprenderás a medida que avances en el proceso.

5. Consideraciones técnicas

Para comenzar este proyecto tendrás que hacer un fork y clonar este repositorio.

  • En este proyecto hay que adoptar las convenciones que los proyectos open source de software usan para hacer seguimiento. Vas a usar Github projects con issues y milestones para priorizar y organizar el trabajo y hacer seguimiento de tu proceso. Dentro de cada milestone crearás los issues que consideres necesarios.

  • La librería y el script ejecutable (herramienta de línea de comando - CLI) deben estar implementados en JavaScript para ser ejecutados 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 un mínimo del 70% de statements, functions, lines y branches. Te recomendamos explorar Jest para tus pruebas unitarias.

  • Para este proyecto no está permitido utilizar async/await.

  • Para este proyecto, hay que decidir si vas a utilizar los módulos CommonJS o ES Modules. Los módulos CommonJS usan la síntaxis require y es el formato de módulos original de Node.js. Si prefieres utilizar ES Modules (import/export), puedes hacerlo, pero ten en cuenta que deberás configurar adecuadamente tu proyecto para que Node.js pueda utilizar este formato. Puedes encontrar más información al respecto aquí. Además, tendrás que configurar Jest para ello también, siguiendo los siguientes pasos. Ten en consideración que Jest considera esto aún como un feature experimental.

  • Para este proyecto, te recomendamos evitar el uso de la función síncrona readFileSync para leer archivos. En su lugar, te sugerimos abordar este desafío de manera asíncrona utilizando readFile. Además, si utilizas el módulo fs/promises, podrás utilizar la versión promisificada de las funciones como readFile.

  • Para disminuir la complejidad de tu algoritmo recursivo, te recomendamos utilizar la versión síncrona de la función para leer directorios, readdirSync.

Descripción de los archivos del proyecto

  • 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, ...), main, bin
  • .editorconfig con configuración para editores de texto. Este archivo no se debe cambiar.
  • .eslintrc con configuración para linter. Este archivo contiene una configuración básica para ESLint, si deseas agregar reglas adicionales como Airbnb deberás modificar este archivo.
  • .gitignore para ignorar node_modules u otras directorios que no deban incluirse en control de versiones (git).
  • test/md-links.spec.js debe contener los tests unitarios para la función mdLinks(). Tu implementación debe pasar estos tests.

Este proyecto lo puedes ir construyendo por hitos. A continuación te sugerimos algunos:

6. Hitos

Recuerda que la mejor manera de abordar un problema es descomponiéndolo en problemas más pequeños. Por esta razón, te recomendamos que completes este proyecto trabajando por hitos. A continuación, encontrarás los hitos que puedes seguir:

7. Hacker edition

Las secciones llamadas Hacker Edition son opcionales. Si terminaste con todo lo anterior y te queda tiempo, intenta completarlas. Así podrás profundizar y/o ejercitar más sobre los objetivos de aprendizaje del proyecto.

  • Puedes agregar la propiedad line a cada objeto link 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.

8. Pistas, tips y lecturas complementarias

Inicia con un diagrama de flujo y/o pseudocódigo

Este proyecto difiere de los anteriores en los que has trabajado, ya que no implica una interfaz web. Todo el desarrollo se llevará a cabo en tu editor y en la consola/terminal.

El proyecto se basa en un proceso lógico compuesto por diferentes pasos. Para comprender mejor lo que debes hacer y planificar tus tareas y objetivos, se recomienda desglosar el proceso en pasos y visualizarlo mediante un diagrama de flujo o escribiendo pseudocódigo

Sugerencias de implementación

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.

  • 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 links con una librería de DOM como JSDOM o Cheerio entre otras).

  • Usando un custom renderer de la librería marked (new marked.Renderer()).

  • Siguiendo otro camino completamente diferente, podríamos usar expresiones regulares (RegExp).

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 😉 Lo importante es que entiendas el código que escribes para lograr la tarea.

¿CommonJS Modules o ES Modules, cual debería usar?

Desde el principio, es importante que tomes una decisión respecto a qué tipo de módulos utilizarás: ES Modules (import/export) o CommonJS Modules (require/module.exports). Ambos cumplen el mismo propósito de modularizar y compartir código. Hasta ahora, Node.js ha empleado mayormente los CommonJS Modules (require) y funcionan sin necesidad de configuraciones adicionales. Sin embargo, en las versiones más recientes de Node.js, también puedes optar por utilizar ES Modules, aunque esto requerirá algunos pasos de configuración adicionales. Si decides utilizar ES Modules, asegúrate de investigar cómo configurar tu proyecto según la versión de Node que estés utilizando. Ten en cuenta esta decisión desde el inicio de tu proyecto, ya que afectará la forma en que importas y exportas módulos en tu código.

¿Cuáles son partes de node son relevantes para este proyecto?

Node ofrece una amplia gama de módulos y funciones, pero no es necesario conocerlos todos antes de comenzar a programar. Los hitos se refieren a partes específicas de Node que puedes explorar, como los módulos fs (readFile, readdirSync) y path. Estos módulos son útiles para realizar operaciones de lectura y escritura de archivos, así como para manipular y trabajar con rutas de archivos en tu código. A medida que avanzas en tu proyecto, puedes investigar más sobre estos módulos y cómo utilizar sus funciones para lograr tareas específicas. ¡No dudes en sumergirte en la programación y explorar los partes relevantes de Node mientras avanzas en tu proyecto!

¿Cómo hago para que mi módulo sea instalable con npm?

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

Por ejemplo, el curriculum-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/curriculum-parser.

Recursos

Hito 1

Hito 2

Hito 3

Hito 4

Hito 5

Otros recursos

9. Para pedir project feedback

  • Un board en github projects con el backlog para la implementación de la librería.

  • un README.md con documentación técnica de la librería y una guía de uso e instalación de la librería.

  • un API mdLinks(path, validate) con los siguientes requisitos (Hito 1 y 2 son los mínimos):

    • El módulo debe exportar una función que cumpla con la interfaz (API) requerida. (Hito 1)
    • Deberá implementar el soporte para archivos individuales. (Hito 1)
    • Deberá implementar la funcionalidad de validación. (Hitos 1 y 2)
    • Deberá ofrecer soporte para directorios. (Hitos 1 al 3)
    • Deberá ofrecer soporte para directorios que pueden contener otros directorios. (Hitos 1 al 5)

  • un CLI (Command Line Interface) que se ejecuta sin errores y tiene el output esperado. Además acepta los parámetros --validate y --stats. Y expone un ejecutable md-links en el path (configurado en el package.json)

  • Pasa tests y linters (npm test). Tests unitarios cubren un mínimo del 70% de coverage tests, es decir statements, functions, lines y branches.
axiosjestlatestnremarkable
@everything-registry/sub-chunk-2148
0.1.0

11 months ago