{"_id":"@alu0101390161/espree-logging","_rev":"1-8cb6490269c51da6e1170a21c6dcd635","name":"@alu0101390161/espree-logging","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@alu0101390161/espree-logging","author":{"name":"Raimon Mejías Hernández","email":"alu0101390161@ull.edu.es","url":"https://crguezl.github.io/"},"description":"Adds logs to javascript code","type":"module","module":"src/logging-espree.js","bin":{"funlog":"bin/log.js"},"scripts":{"test":"mocha test/test.mjs","cov":"nyc npm run test","clear":"rm -r test/js/*.js"},"dependencies":{"acorn":"^8.8.2","commander":"^10.0.0","escodegen":"^2.0.0","espree":"^9.4.1","estraverse":"^5.2.0","underscore":"^1.12.0","chai":"^4.3.6","mocha":"^9.2.0","nyc":"^15.1.0"},"version":"1.0.0","devDependencies":{"mocha":"^10.2.0"},"main":"src/logging-espree.js","directories":{"test":"test"},"repository":{"type":"git","url":"git+ssh://git@github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161.git"},"gitHead":"28f2df7142c288de106c46450158d4a4e75b4f6b","bugs":{"url":"https://github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161/issues"},"homepage":"https://github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161#readme","_id":"@alu0101390161/espree-logging@1.0.0","_nodeVersion":"19.6.0","_npmVersion":"9.4.0","dist":{"integrity":"sha512-M0EcM+jtol5F8hX70vqiCzpP0EJynI/ndHL9b6CIbxCjWOKIruXS4OM52wzbcJ2oM8modpK2jIBIcaOg3rcTtQ==","shasum":"45000b8e926ea85fae5e2c358b2c361e819278c0","tarball":"https://registry.npmjs.org/@alu0101390161/espree-logging/-/espree-logging-1.0.0.tgz","fileCount":40,"unpackedSize":62208,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHnFeCgWyI9UWWKrsYvvfCvTz56+gvacgpvFtGgbOOmwAiBZJ/xlQpSHlJ+hqwANiKzkRzZeOsOIWil5Vmi8EhWumQ=="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJj/9xkACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmo4zBAAjBB6WaoVIG4sBjhnHRO8SeG1d/LdJ4V3IexmWdK2jvUZQ6nb\r\nn1RI0tek6fOlTYs6Q0GvZXEJa4JlhqYRhjynJBSCEesiEPa1IjLz6rKMAS6Y\r\nm5yjyp7u8Y9ToLnA+5fTD6hiuezRdrT+YR1NuhqmYlftT/6INnKT4ZzWvJY8\r\n+pp16p3R5j9JDs2l9LNaGdF1meYFoMWsyv+fkb5njk8XfFC7TMFywB+km2/Z\r\nLswHIAmuImdZs44tNb4SCnBGr4nvBi06quWcQ7/xNM2f1JQwharWMB0cUbSD\r\ntKETvOA/PYXLWhIQRGrYlZvafXcywBL1VwCF3b6pd9wWiMzQeLZmGLX0363R\r\nLJ5SrTb3OgHbgAbeOV0g7Ju1w7o1SCPLxVVFoSqzPZxY4lc6lVZMsq2gh6cb\r\ncTDZxgm+2q3GthCPftzyNT+hn2sHR26GnlNXO7YXKnZKc27hzYj5oovAXrkZ\r\niISKp5aeSYtk3xRM5DNHT0FW3tPfanqpp6aajYk8MY/xgUirJIlMXrnbFs1m\r\nUU7VYuG5sqkt7nFddQc3G2XZfMIO05y0FygDkvI2Ww1GAh+53N6jRUhUTmcU\r\npip6OBRFldLAbWJq9NjQ7zop4R1o+9GufmN0Mbs1cios2Eez86fDVj1uJw1a\r\nwU//341dpISNVLtfDQU7s0bS1igH45mHklw=\r\n=TRkK\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"raimon_mejias","email":"alu0101390161@ull.edu.es"},"maintainers":[{"name":"raimon_mejias","email":"alu0101390161@ull.edu.es"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/espree-logging_1.0.0_1677712484612_0.21361285552891185"},"_hasShrinkwrap":false},"1.1.0":{"name":"@alu0101390161/espree-logging","author":{"name":"Raimon Mejías Hernández","email":"alu0101390161@ull.edu.es","url":"https://crguezl.github.io/"},"description":"Adds logs to javascript code","type":"module","module":"src/logging-espree.js","bin":{"funlog":"bin/log.js"},"scripts":{"test":"mocha test/test.mjs","cov":"nyc npm run test","clear":"rm -r test/js/*.js"},"dependencies":{"@alu0101390161/espree-logging":"^1.0.0","acorn":"^8.8.2","chai":"^4.3.6","commander":"^10.0.0","escodegen":"^2.0.0","espree":"^9.4.1","estraverse":"^5.2.0","mocha":"^9.2.0","nyc":"^15.1.0","underscore":"^1.12.0"},"version":"1.1.0","devDependencies":{"mocha":"^10.2.0"},"main":"src/logging-espree.js","directories":{"test":"test"},"repository":{"type":"git","url":"git+ssh://git@github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161.git"},"gitHead":"c70ea903bdca9b3b239b9a046c44d88f7bae98da","bugs":{"url":"https://github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161/issues"},"homepage":"https://github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161#readme","_id":"@alu0101390161/espree-logging@1.1.0","_nodeVersion":"19.6.0","_npmVersion":"9.4.0","dist":{"integrity":"sha512-y/QklaBUaLEFm2A14PkcGAgS0apzvGlz4uhtI4vey2XKMLf5o31I7tmH09tLS2qFK2YUtNMBzgXDb91osegX7g==","shasum":"d0e3fd26401f39aa86a240971758d048496c0490","tarball":"https://registry.npmjs.org/@alu0101390161/espree-logging/-/espree-logging-1.1.0.tgz","fileCount":44,"unpackedSize":127186,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCQvEfXFF1lT0fddyk8+bwGR880tSvUC6x9Qp1t/7DacQIgaet8ffNGq8trvnrVHiSgMVzg5PgE5Y8YUan6yify4Uc="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJkAMjEACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmrz+xAAklavYqNRKwMjrB2RCUjaHzcwruHHg226XQ9vdG1o1H6Zb0fh\r\niHIhquGDarKlvgYfmKylr1cOz8soc74DpmqrW1P3jWRwT8aHruxWJ2sXtX2Y\r\nN7cPgsqhN6Q5E+OEh9zbS6t3NO4cTTu/NtLptD5Qca1Q/RpyPXBMJ7Q5vGiM\r\n9JEt4uoqSgSELxyBOiWFBTqXLgul0yRoxlFcdZzZez94w/4GUE/glImLgFj1\r\nBNyo1Zd9Z6lWL7rsOvF1Kzh/vvk2yghV7J/NHvUqUp8oOwMyMbpm5Z+6Lt7H\r\nRW+it/cKRw70TNNBxgGfuoU3VePgbnKG8L5cQLU+dFquwve4R/dYaskP597L\r\nR2tzAuNFgWVkON/X/IZPn8uTYu8N6fre/h/hTOkyPxfKp2ilWv0HhnfMhPxN\r\nq478u6s4V5sTOOnPw3JnEDnTEogny6nZaoJkRnqsMatJyVDc/M3nlkPTpHPV\r\nDrHSw5Uw7w5RN2tWo//eiC+sYw7+OoscbZVnz+hkS4/tLmvwU3vp9eY6LkhC\r\nPlN1Orx9oI/tSDHJMa+t4dD5pJQBseVX3Vhu1EC6oMk9E53k6P1JSFOSJRvH\r\nlrVePNCxpG30FgE8tVPF3WI8K+ew7Er/s+JBv34K5gJwamCgJJitj6UBQsI9\r\nEPIODD8ETIbw9et3Zaqy8XgC7coZRQanDRU=\r\n=jEvT\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"raimon_mejias","email":"alu0101390161@ull.edu.es"},"maintainers":[{"name":"raimon_mejias","email":"alu0101390161@ull.edu.es"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/espree-logging_1.1.0_1677772996008_0.17655512564004194"},"_hasShrinkwrap":false}},"time":{"created":"2023-03-01T23:14:44.499Z","1.0.0":"2023-03-01T23:14:44.763Z","modified":"2023-03-02T16:03:16.371Z","1.1.0":"2023-03-02T16:03:16.190Z"},"maintainers":[{"name":"raimon_mejias","email":"alu0101390161@ull.edu.es"}],"description":"Adds logs to javascript code","homepage":"https://github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161#readme","repository":{"type":"git","url":"git+ssh://git@github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161.git"},"author":{"name":"Raimon Mejías Hernández","email":"alu0101390161@ull.edu.es","url":"https://crguezl.github.io/"},"bugs":{"url":"https://github.com/ULL-ESIT-PL-2223/espree-logging-raimon-mejias-hernandez-alu0101390161/issues"},"readme":"[![Open in Codespaces](https://classroom.github.com/assets/launch-codespace-f4981d0f882b2a3f0472912d15f9806d57e124e0fc890972558857b51b24a6f9.svg)](https://classroom.github.com/open-in-codespaces?assignment_repo_id=10330046)\n# Lab: Espree logging\n\n## Información de la práctica\n\n- Universidad de La Laguna\n- Escuela Superior de Ingeniería y Tecnología\n- Grado en Ingeniería Informatica\n- Curso: 3º\n- Asignatura: Procesadores de Lenguajes\n- Fecha: 01/03/2023\n- Autor: Raimon Mejías Hernández\n- Correo: alu0101390161@ull.edu.es\n\n## listado de las tareas a realizar \n\n* Utilizar commander para la línea de comandos \n  * Opciones en la línea de comandos (-V(--version),, -o(--output), -h(--help))\n* Añadir mensaje de logs a la entrada de las funciones\n  * Reto 1: Soportar las Arrow functions\n  * Reto 2: Indicar el número de línea en la que se encuentra la función\n* Realizar test con Mocha\n* Realizar un estudio de cubrimiento con nyc\n* Realizar integración continua con GitHub Actions\n* Crear Scripts para ejecutar el programa\n* Documentar el código utilizando JSDoc\n* Publicar el paquete en npmjs\n* Redactar el informe\n\n## Tareas realizadas\n\nA continuación se detallan paso a paso todas las tareas realizadas\n\n## Utilizar commander para la línea de comandos \n\nUtilizando la librería commander se puede realizar el paso de argumentos al programa de una manera sencilla y rápida.\nIndicando en `Program` Todos los argumentos y opciones que nuestro programa permite, realizando por ultimo una lectura de\nlos argumentos del programa.\n\n```JavaScript\nprogram\n  .version(version)\n  .argument(\"<filename>\", 'file with the original code')\n  .option(\"-o, --output <filename>\", \"file in which to write the output\")\n  .action((filename, options) => {\n    transpile(filename, options.output);\n  });\n\nprogram.parse(process.argv);\n```\n\n### Opciones de la línea de comandos\n\n- <fichero>  Fichero que contiene una función escrita en JS, del cual se creara un AST\n- -V --version: Muestra la versión actual del programa\n- -o --output <fichero>: Vuelca el nuevo código JS generado a partir de la modificación del AST original.\n- -h --help : Muestra la información de ayuda del programa\n\n## Añadir mensaje de logs a la entrada de las funciones\n\nUtilizando la plantilla del fichero `logging-espree.js`, se ha procedido a rellenar las funciones con el código necesario:\n\n```JavaScript\nexport async function transpile(inputFile, outputFile) {\n  try {\n    const code = await fs.readFile(inputFile, 'utf-8');\n    const ast = addLogging(code);\n    if (!outputFile) { \n      console.log(ast); \n    } else {\n      await fs.writeFile(outputFile, ast);\n    }\n  } catch (SyntaxError) {\n    console.log('espree couldn\\'t create the ast while transpiling the inputfile');\n    console.log(`${SyntaxError.name}: ${SyntaxError.message} at line ${SyntaxError.lineNumber}`);\n  }\n}\n```\nLa función transpile es muy parecida a la de las prácticas anteriores, con la única diferencia de realizar la llamada a la función addLogging, la cual\nes otra función que se debe implementar en esta práctica.\n\n```JavaScript\nexport function addLogging(code) {\n  let ast = espree.parse(code, {ecmaVersion: 12, loc: true});\n  estraverse.traverse(ast, { \n    enter: function(node, parent) {\n        if (node.type === 'FunctionDeclaration' || \n            node.type === 'FunctionExpression'  ||\n            node.type === 'ArrowFunctionExpression') {\n              addBeforeCode(node);\n            }\n        }\n    });\n  return escodegen.generate(ast);\n}\n```\nLa función addLogging se encarga de general el AST del código JS leído originalmente, para luego utilizar la función traverse de la librería estraverse para\nrealizar la modificación de los nodos de tipo función, llamando así a la función addBeforeCode.\n\n```JavaScript\nfunction addBeforeCode(node) {\n  const name = (node.id)? node.id.name : '<anonymous function>';\n  const line = node.loc.start.line;\n  let parameters = '';\n  for (let i = 0; i < node.params.length; i++) { \n    parameters +=  '${ ' + node.params[i].name + ' }' + ((i < node.params.length - 1)? ', ' : '');\n  }\n  const beforeCode = `console.log(\\`Entering ${name}(${parameters}) at line ${line}\\`)`;\n  const beforeNodes = espree.parse(beforeCode, {ecmaVersion: 12}).body;\n  node.body.body = beforeNodes.concat(node.body.body);\n}\n```\nLa función addBeforeCode se encarga de conseguir toda la información necesaria para generar el console.log que se va a añadir justo debajo de la \ndeclaración de la función, por ultimo modifica el AST original añadiéndole a la función nuevos nodos en el body.\n\n### Indicar los valores de los argumentos\n\nComo se puede observar en el código de la función addBeforeCode, se realiza un recorrido por los parametros de la función, obteniendo así los\nnombres de los parametros\n\n```javascript\n  let parameters = '';\n  for (let i = 0; i < node.params.length; i++) { \n    parameters +=  '${ ' + node.params[i].name + ' }' + ((i < node.params.length - 1)? ', ' : '');\n  }\n```\n\n### Reto 1: Soportar las funciones Arrow\n\nPara permitir que el código de `logging-espree.js` soporte la aparición de expresiones del estilo:\n\n```JavaScript\na => { return a; }\n(a, b) => { \n  let c = a + b;\n  return c;\n}\n```\nSe ha de añadir, a las condiciones del if dentro de la función traverse, la condición `node.type === 'ArrowFunctionExpression'` Permitiendo así detectar los nodos de dicho tipo y realizando la modificación pertinente.\n\n### Reto 2: Indicar el número de línea en la que se encuentra la función\n\nPara obtener el número de línea en la que se encuentra la función detectada se ha incluir en los parámetros pasados a la función `espree.parse()` el objeto `{loc: true}`\nObteniendo así un AST que contiene los campos loc.start.line, consiguiendo así el número de línea de la función.\n\n```JavaScript \nlet ast = espree.parse(code, {ecmaVersion: 12, loc: true}); // Función AddLogging\nconst line = node.loc.start.line; // Funcion addBeforeCode\n```\n\n### Documentar el código utilizando JSDoc\n\nJunto con el código creado se ha realizado una documentación exhaustiva del código, explicando toda la información necesaria para entender el código creado.\nSe ha utilizado el formato JSDoc para la realización de los comentarios de cabecera de las funciones y del programa.\n\n```JavaScript \n/**\n * @desc It takes a string and convert it to an AST, then proceeds to \n * insert the new console.log in each function that find\n * @param {String} code - An string that contain a function\n * @returns Returns the new JavaScript code generated from the modified AST\n */\n```\n\nEjemplo de un comentario JSDoc para la función `addLogging`\n\n## Tests and Covering\n\nComo se ha relizado en anteriores prácticas se ha utilizado la metodología de Stubbing para relizar modificaciones en el método console.log permitiendo así utilizarlo para realizar\nlas comprobaciones de los tests.\n\n```JavaScript\nasync function calculate(outputLog, correctFile) {\n  const correct = await fs.readFile(correctFile, 'utf-8');\n  let log = console.log;\n  let result = ' ';\n  console.log = function (...space) { result += space.join(''); }\n  eval(outputLog);\n  console.log = log;\n  return [result, correct];\n}\n```\n\nAntes de realizar el calculo primero se debe realizar el transpile, para ello se llama a: \n\n```JavaScript\nasync function getLog(inputFile, outputFile, expectedFile) {\n  await transpile(inputFile, outputFile);\n  const output = await fs.readFile(outputFile, 'utf-8');\n  const expected = await fs.readFile(expectedFile, 'utf-8');\n  return [output, expected];  \n}\n```\n\nPor ultimo se realizan iterativamente los tests que se encuentran definidos en el fichero `test-description.mjs`\n\n### Realización del covering con nyc\n\nPara la realización de esta práctica se ha pedido que en el package.json se indique el campo \"type\" con \"module\". Esto tiene un efecto negativo en la ejecución del estudio de cubrimiento del código con nyc, realizando una búsqueda en internet se encuentra que nyc no soporta la ejecución con el tipo module: \n\n[problea_nyc](https://github.com/istanbuljs/nyc/issues/1353)\n\n## Realizar integración continua con GitHub Actions\n\nUtilizando el fichero creado en la práctica anterior se ha realizado la integración continua automatica con GitHub Actions \n\n## Crear Scripts para ejecutar el programa\n\nA continuación se listan todos los scripts que se pueden ejecutar en el package.json\n\n- `npm run test`: Realiza la ejecución de todos los tests\n- `npm run cov`: Realiza la ejecución de todos los tests dando como resultado el estudio de cobertura\n- `npm run clear`: Borra todos los ficheros temporales .js del directorio test/js\n\n## Publicar el paquete en npmjs\n\n\nPara publicar el paquete enn npmjs primero se deben realizar los siguientes pasos:\n\n* Crear una cuenta en la página de npm\n* Modificar el package.json para añadir toda la información necesaria para el modulo\n* Comprobar que el modulo esta correctamente exportado\n* Crear una organización en npm\n* Ejecutar npm publish --access public la primera vez \n\n![publish](docs/informe/npm_publish.png)\n\n### Comprobar si todo ha ido bien\n\nTras publicarlo se debe comprobar que el paquete npmjs se ha publicado correctamente, para ello se realiza `npm install @alu0101390161/espree-logging`\nDando como resultado:\n\n![npm_install](docs/informe/npm_install.png)\n\nPor ultimo para comprobar que se han exportado las funciones correctas se prueba el ejecutable generado utilizando `npx funlog`\n\n![npx_funlog](docs/informe/npx_funlog.png)\n\n## References \n\n* [Lab espree logging](https://ull-esit-gradoii-pl.github.io//practicas/espree-logging)\n* Examples at [Repo ULL-ESIT-GRADOII-PL/esprima-pegjs-jsconfeu-talk](https://github.com/ULL-ESIT-GRADOII-PL/esprima-pegjs-jsconfeu-talk)\n* Example [crguezl/hello-jison](https://github.com/crguezl/hello-jison)\n* [Espree](https://github.com/eslint/espree)\n  * [Options for parse and tokenize methods](https://github.com/eslint/espree#options)\n* <a href=\"https://astexplorer.net/\" target=\"_blank\">astexplorer.net demo</a>\n* [idgrep.js](https://github.com/ULL-ESIT-GRADOII-PL/esprima-pegjs-jsconfeu-talk/blob/master/idgrep.js)\n* [Introducción a los Compiladores](https://ull-esit-gradoii-pl.github.io/temas/introduccion-a-pl/esprima.html) con Jison y Espree","readmeFilename":"README.md"}