Blade Grade Web

Validador académico utilizado para los proyectos de la materia de Diseño y Programación Gráfica.

Durante el primer parcial se utilizarán:

• HTML
• CSS
• JavaScript

Posteriormente se incorporarán las reglas correspondientes a:

• Angular
• Consumo de servicios mediante API

El validador permite revisar:

• Estructura del proyecto.
• Nombres de exámenes y prácticas.
• Código HTML.
• Código CSS.
• Código JavaScript.
• Reglas definidas para cada parcial.

La validación local permite detectar problemas antes de enviar el código al repositorio.

1. Requisitos

Antes de comenzar debes tener instalado:

• Git
• Node.js
• npm

Para administrar las dependencias del proyecto se recomienda utilizar:

• pnpm

2. Instalar Node.js

Se recomienda utilizar una versión LTS de Node.js. Descargar Node.js

Windows

Descarga e instala Node.js desde el sitio oficial.

Después verifica la instalación:

node --version
npm --version

Linux

Se recomienda utilizar NVM.

Instala NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Cierra y vuelve a abrir la terminal.

Instala Node.js LTS:

nvm install --lts

Activa la versión:

nvm use --lts

Verifica:

node --version
npm --version

3. Instalar pnpm utilizando npx

Con Node.js y npm instalados puedes configurar pnpm ejecutando:

npx get-pnpm

Después de ejecutar el comando, cierra y vuelve a abrir la terminal.

Verifica la instalación:

pnpm --version

Si muestra una versión, pnpm está correctamente configurado.

También puedes utilizar pnpm directamente mediante npx:

npx pnpm --version

4. Crear el proyecto

Crea una carpeta para tu proyecto:

mkdir proyecto-sis313
cd proyecto-sis313

Inicializa el proyecto con pnpm:

pnpm init

También puedes ejecutar:

npx pnpm init

5. Estructura del proyecto

El proyecto utilizará las siguientes carpetas principales:

proyecto-sis313/
├── examenes/
│   └── primer-parcial/
│       ├── assets/
│       │   ├── css/
│       │   ├── js/
│       │   └── image/
│       └── index.html
│
├── practicas/
│   └── practica-1/
│
├── package.json
└── README.md

Las carpetas:

examenes/
practicas/

son obligatorias y no deben cambiar de nombre.

6. Crear la estructura

Linux

mkdir -p examenes/primer-parcial/assets/{css,js,image}
mkdir -p practicas/practica-1

touch examenes/primer-parcial/index.html
touch examenes/primer-parcial/assets/css/style.css
touch examenes/primer-parcial/assets/js/script.js

Windows PowerShell

mkdir examenes
mkdir examenes\primer-parcial
mkdir examenes\primer-parcial\assets
mkdir examenes\primer-parcial\assets\css
mkdir examenes\primer-parcial\assets\js
mkdir examenes\primer-parcial\assets\image

mkdir practicas
mkdir practicas\practica-1

New-Item examenes\primer-parcial\index.html
New-Item examenes\primer-parcial\assets\css\style.css
New-Item examenes\primer-parcial\assets\js\script.js

7. Instalar Blade Grade Web

Instala el evaluador como dependencia de desarrollo:

pnpm add -D blade-grade-web

Si todavía no tienes disponible el comando pnpm, puedes utilizar:

npx pnpm add -D blade-grade-web

Esto agregará automáticamente blade-grade-web al package.json.

8. Configurar package.json

Agrega el comando:

{
  "scripts": {
    "check": "blade-grade-web"
  }
}

Por ejemplo:

{
  "name": "proyecto-sis313",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "check": "blade-grade-web"
  },
  "devDependencies": {
    "blade-grade-web": "^0.0.2"
  }
}

La versión de blade-grade-web puede cambiar con las actualizaciones.

No es necesario escribir manualmente la versión si utilizaste:

pnpm add -D blade-grade-web

9. Utilizar Blade Grade Web con pnpm

Para evaluar el Primer Parcial:

pnpm run check examenes primer-parcial

También puedes utilizar la forma abreviada:

pnpm check examenes primer-parcial

Para evaluar una práctica:

pnpm run check practicas practica-1

o:

pnpm check practicas practica-1

Importante: con pnpm no agregues -- entre check y los argumentos.

Correcto:

pnpm check examenes primer-parcial

Incorrecto:

pnpm check -- examenes primer-parcial

10. Ejecutar directamente el evaluador

También puedes ejecutar el paquete directamente:

pnpm exec blade-grade-web examenes primer-parcial

Para una práctica:

pnpm exec blade-grade-web practicas practica-1

La forma recomendada para los proyectos de la materia será:

pnpm check examenes primer-parcial

11. Validar la estructura

El evaluador comprueba primero la estructura general del proyecto.

Por ejemplo:

proyecto-sis313/
├── examenes/
└── practicas/

Si cambias:

examenes/

por:

examenesxxx/

y ejecutas:

pnpm check examenes primer-parcial

la evaluación debe fallar indicando que falta:

examenes/

Vuelve a colocar el nombre correcto antes de continuar.

12. Prueba con errores intencionales

Antes de comenzar a trabajar normalmente realizaremos una prueba agregando errores intencionales.

Esto permite comprobar que:

• HTMLHint está funcionando.
• Stylelint está funcionando.
• ESLint está funcionando.
• Blade Grade Web está utilizando las reglas del Primer Parcial.

13. HTML con errores

Edita:

examenes/primer-parcial/index.html

Coloca:

<html>
  <head>
    <title>Mi proyecto</title>
  </head>

  <body>
    <div id="principal">
      <img src="" />

      <button onclick="alert('hola')">Presionar</button>
    </div>
  </body>
</html>

Este código contiene errores y malas prácticas que deberán ser detectados por las reglas configuradas.

14. CSS con errores

Edita:

examenes/primer-parcial/assets/css/style.css

Coloca:

#principal {
  color: #GGGGGG;
  margin: 0px;
  color: red !important;
}

Entre los problemas que puede detectar el evaluador se encuentran:

Too many ID selectors
Disallowed unit

Por ejemplo:

#principal

no cumple la regla que evita utilizar identificadores como selectores CSS.

También:

margin: 0px;

utiliza innecesariamente una unidad cuando el valor es cero.

15. JavaScript con errores

Edita:

examenes/primer-parcial/assets/js/script.js

Coloca:

var nombre = "David";

if (nombre == "David") {
  console.log("Hola");
}

eval("console.log('test')");

El evaluador deberá detectar problemas como:

Unexpected var, use let or const instead
Expected '===' and instead saw '=='
Unexpected console statement
eval can be harmful

16. Ejecutar la prueba

Ejecuta:

pnpm check examenes primer-parcial

El evaluador realizará:

VALIDANDO ESTRUCTURA

OBJETIVO DE EVALUACIÓN

HTML

CSS

JavaScript

Como agregamos errores intencionalmente, la evaluación debe fallar.

Al finalizar deberá indicar que la evaluación encontró errores.

Debes revisar cada problema mostrado en la terminal antes de continuar.

17. Corregir HTML

Reemplaza el contenido de:

examenes/primer-parcial/index.html

por:

<!DOCTYPE html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />

    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>Mi proyecto</title>

    <link rel="stylesheet" href="./assets/css/style.css" />
  </head>

  <body>
    <header>
      <h1>Mi proyecto</h1>
    </header>

    <main>
      <div class="principal">
        <img src="./assets/image/logo.png" alt="Logo del proyecto" />

        <button id="button-saludar" type="button">Presionar</button>
      </div>
    </main>

    <script src="./assets/js/script.js"></script>
  </body>
</html>

18. Corregir CSS

Reemplaza:

examenes/primer-parcial/assets/css/style.css

por:

.principal {
  margin: 0;
  color: red;
}

Se reemplazó:

#principal

por:

.principal

y:

margin: 0px;

por:

margin: 0;

19. Corregir JavaScript

Reemplaza:

examenes/primer-parcial/assets/js/script.js

por:

const nombre = "David";

if (nombre === "David") {
  console.warn("Hola");
}

const buttonSaludar = document.querySelector("#button-saludar");

buttonSaludar.addEventListener("click", () => {
  console.warn("Hola");
});

20. Ejecutar nuevamente la validación

Ejecuta:

pnpm check examenes primer-parcial

El evaluador comprobará nuevamente:

Estructura
HTML
CSS
JavaScript

Cuando todo esté correcto deberá finalizar indicando:

Todas las validaciones pasaron.

21. Validar una práctica

Para validar:

practica-1

ejecuta:

pnpm check practicas practica-1

Las prácticas utilizan las reglas correspondientes al parcial al que fueron asignadas.

Actualmente:

practica-1 -> primer-parcial
practica-2 -> primer-parcial
practica-3 -> primer-parcial

Por lo tanto estas prácticas utilizan las reglas del Primer Parcial.

22. Nombres de los exámenes

Los nombres establecidos son:

primer-parcial
segundo-parcial
tercer-parcial
examen-final

La estructura general podrá ser:

examenes/
├── primer-parcial/
├── segundo-parcial/
├── tercer-parcial/
└── examen-final/

No debes utilizar nombres diferentes.

Ejemplos incorrectos:

parcial-1
primer_parcial
primerparcial
primer parcial
final

No es necesario crear todos los exámenes desde el inicio.

Cada parcial será habilitado cuando corresponda.

23. Nombres de las prácticas

Las prácticas deben utilizar:

practica-N

Ejemplos:

practica-1
practica-2
practica-3

No utilices:

practica_1
practica01
pr-1
practicas-1
practica 1

Las prácticas serán habilitadas progresivamente durante la materia.

24. Validar antes de realizar un commit

Antes de realizar un commit debes validar el trabajo correspondiente.

Para un examen:

pnpm check examenes primer-parcial

Para una práctica:

pnpm check practicas practica-1

Si existen errores, corrígelos antes de continuar.

25. Formato de commits

Para un examen:

git add .

git commit -m "feat: completa diseño [examenes][primer-parcial]"

Para una práctica:

git add .

git commit -m "feat: completa practica [practicas][practica-1]"

Finalmente:

git push

El texto entre corchetes permite determinar qué parte del proyecto debe ser evaluada.

Para un examen:

[examenes][primer-parcial]

Para una práctica:

[practicas][practica-1]

26. Validación local y evaluación oficial

La validación local permite detectar errores antes de subir el código.

Ejemplo:

pnpm check examenes primer-parcial

La evaluación mediante GitLab CI/CD será la validación oficial.

Modificar manualmente archivos dentro de:

node_modules/

no modifica la evaluación oficial.

El pipeline instalará nuevamente las dependencias antes de ejecutar Blade Grade Web.

27. No subir node_modules

La carpeta:

node_modules/

no debe enviarse al repositorio.

Crea un archivo:

.gitignore

con:

node_modules/

.DS_Store
Thumbs.db

El archivo de bloqueo de pnpm sí debe mantenerse en Git:

pnpm-lock.yaml

28. Instalar el proyecto en otra computadora

Después de clonar el proyecto:

git clone URL_DEL_REPOSITORIO

entra a la carpeta:

cd proyecto-sis313

e instala las dependencias:

pnpm install

No necesitas copiar node_modules.

pnpm instalará nuevamente:

blade-grade-web

y sus dependencias.

29. Actualizar Blade Grade Web

Para actualizar el evaluador:

pnpm update blade-grade-web

También puedes instalar explícitamente la versión más reciente:

pnpm add -D blade-grade-web@latest

Después puedes comprobar nuevamente:

pnpm check examenes primer-parcial

30. Comandos principales

Instalar pnpm:

npx pnpm@latest setup

Verificar pnpm:

pnpm --version

Inicializar proyecto:

pnpm init

Instalar Blade Grade Web:

pnpm add -D blade-grade-web

Instalar las dependencias:

pnpm install

Validar Primer Parcial:

pnpm check examenes primer-parcial

Validar practica-1:

pnpm check practicas practica-1

Ejecutar directamente el evaluador:

pnpm exec blade-grade-web examenes primer-parcial

Actualizar Blade Grade Web:

pnpm update blade-grade-web

31. Flujo recomendado

El flujo de trabajo recomendado es:

Desarrollar
    |
    v
pnpm check examenes primer-parcial
    |
    v
Revisar errores
    |
    v
Corregir errores
    |
    v
Ejecutar nuevamente el validador
    |
    v
Validación correcta
    |
    v
git add .
    |
    v
git commit
    |
    v
git push
    |
    v
GitLab CI/CD

El validador debe utilizarse durante el desarrollo para detectar y corregir problemas antes de realizar la entrega.