07
Estilos, tácticas y decisiones

Decidir, documentar y evaluar una arquitectura

Estilos, tácticas y decisiones

Semana 7 — Decidir, documentar y evaluar una arquitectura

Objetivos

  • Escribir un ADR con contexto, alternativas, decisión y consecuencias, y explicar por qué un ADR no se reescribe.
  • Documentar una arquitectura con vistas elegidas para sus lectores: los cuatro niveles de C4 y las doce secciones de arc42.
  • Diseñar por iteraciones a partir de los atributos de calidad (ADD): elegir qué refinar, qué escenarios atender y con qué conceptos de diseño.
  • Evaluar una arquitectura con ATAM: recorrer los escenarios del utility tree sobre los enfoques de arquitectura y encontrar riesgos, puntos de sensibilidad y trade-offs.

Sesión A — Decidir y documentar: ADR, vistas, C4 y arc42

Lecturas:

Lecturas complementarias:

  • MADR, un template de ADR con alternativas consideradas, y adr.github.io.
  • arc42: las doce secciones, con ejemplos.
  • Richards y Ford, Fundamentals of Software Architecture (2.ª ed.), cap. 21 Architectural Decisions y cap. 23 Diagramming Architecture.

Temas:

  • Para quién se documenta: para quien construye, para quien llega al equipo dentro de un año, para quien evalúa y para quien opera. Cada lector necesita una vista distinta; un solo diagrama que intenta mostrar todo no le sirve a ninguno.
  • Vista: la representación de una estructura. El libro propone documentar las vistas relevantes (de módulos, de componentes y conectores, de asignación) y, aparte, lo que aplica a más de una. Qué vistas elegir depende de qué stakeholders hay y qué necesitan saber.
  • Lo que lleva una vista: el diagrama principal, el catálogo de elementos (qué es cada caja, con su interfaz y su comportamiento), la leyenda, y la justificación de por qué es así. Un diagrama sin leyenda no es documentación: cajas y flechas con significado privado.
  • C4 (Simon Brown): cuatro niveles de zoom sobre el mismo sistema. Contexto: el sistema, las personas y los sistemas externos. Contenedores: las aplicaciones y los almacenes de datos que corren por separado. Componentes: las partes de un contenedor. Código: casi nunca se dibuja. Más los diagramas complementarios: dinámico (una interacción paso a paso) y de despliegue. Reglas: toda caja dice qué es, qué hace y con qué tecnología; toda flecha tiene una dirección, un verbo y un protocolo.
  • Diagramas como texto: viven en el repositorio, se revisan con el código y se actualizan en el mismo cambio. Un diagrama que no se puede comparar entre versiones envejece sin que nadie lo note.
  • arc42: un template de doce secciones para el documento completo: introducción y objetivos, restricciones, contexto y alcance, estrategia de solución, vista de bloques, vista de ejecución, vista de despliegue, conceptos transversales, decisiones de arquitectura, requisitos de calidad, riesgos y deuda técnica, glosario. No hay que llenarlas todas: se llena lo que alguien va a leer.
  • ADR (Nygard): un documento corto por decisión, numerado y guardado en el repositorio. Secciones: título, estado (propuesto, aceptado, rechazado, obsoleto o reemplazado por el ADR N), contexto (las fuerzas en juego, incluido el escenario de calidad), decisión, y consecuencias, las buenas y las malas. El curso agrega las alternativas consideradas y por qué se descartaron.
  • Un ADR no se reescribe: si la decisión cambia, se escribe otro que lo reemplaza y en el anterior solo cambia el estado. El valor está en poder reconstruir qué se sabía cuando se decidió.
  • Qué merece un ADR: lo que cuesta cambiar, lo que alguien va a preguntar “¿por qué está así?”, y lo que parece raro sin su contexto. Lo que no: el nombre de una variable.
  • Error común: un ADR sin alternativas (“decidimos usar Redis”). Sin lo que se descartó, nadie puede saber si la decisión sigue vigente cuando cambie el contexto.
  • Error común: documentar al final, para justificar lo que ya se hizo. El ADR sirve cuando se escribe mientras se decide.

Sesión B — Diseñar y evaluar: diseño guiado por atributos y ATAM · ✂️ risk storming

Lecturas:

  • Software Architecture in Practice, cap. 20 Designing an Architecture y cap. 21 Evaluating an Architecture.
  • Lectura libre: Kazman, Klein y Clements, ATAM: Method for Architecture Evaluation (SEI, 2000), sección 3 (los nueve pasos) y sección 7 (lo que el método produce) (PDF).

Lecturas complementarias:

  • Fundamentals of Software Architecture (2.ª ed.), cap. 22 Analyzing Architecture Risk.
  • ✂️ Simon Brown, Risk-storming.

Temas:

  • Diseñar es decidir con un método. Diseño guiado por atributos (ADD): primero se revisan las entradas (propósito, requisitos funcionales principales, escenarios de calidad, restricciones) y después se itera. Los pasos de una iteración: fijar el objetivo de la iteración; elegir qué elemento del sistema se refina; elegir conceptos de diseño (estilos, tácticas, tecnologías) que atiendan los escenarios elegidos; instanciar los elementos y asignarles responsabilidades e interfaces; dibujar las vistas y registrar las decisiones; analizar el diseño y decidir si hace falta otra iteración.
  • Lo que ADD ordena: se empieza por los escenarios más importantes, no por la tecnología; cada decisión queda atada a un escenario, y se sabe cuándo parar (cuando los escenarios prioritarios tienen respuesta).
  • Generar y probar: una decisión de diseño es una hipótesis. Se prueba con un análisis, un prototipo o una medición. El proyecto del curso hace eso en cada entrega.
  • Evaluar antes de construir: es mucho más barato encontrar un riesgo en una reunión que en producción. Formas de evaluar, de menos a más formales: una revisión entre pares, un recorrido de escenarios, ATAM.
  • ATAM (Architecture Tradeoff Analysis Method): reúne a quienes diseñaron y a los stakeholders. Sus nueve pasos: presentar el método; presentar los objetivos del negocio; presentar la arquitectura; identificar los enfoques de arquitectura; generar el utility tree; analizar los enfoques frente a los escenarios más importantes; lluvia de ideas y priorización de escenarios con todos los stakeholders; analizar de nuevo con esos escenarios; presentar los resultados.
  • Lo que produce: riesgos (decisiones que pueden impedir un escenario), no riesgos (decisiones que se analizaron y están bien), puntos de sensibilidad (una decisión de la que depende mucho la respuesta de un atributo) y puntos de trade-off (una decisión que afecta a dos atributos en sentidos opuestos). Y los temas de riesgo, lo que varios riesgos tienen en común (el término no está en el reporte de 2000; viene de descripciones posteriores del método).
  • Ejemplo en Tinkuy: “la pasarela se llama dentro de la transacción” es un punto de sensibilidad para la latencia y un riesgo para la disponibilidad; “TTL de cinco segundos en la cache del catálogo” es un punto de trade-off entre rendimiento y actualidad de los datos.
  • Lo que ATAM no hace: no dice si la arquitectura es buena, no da números y no reemplaza a medir. Dice dónde mirar.
  • Una versión liviana para un equipo pequeño: una hora, el utility tree, los tres escenarios (A, A), y por cada uno la pregunta “¿qué decisión de nuestro diseño lo hace posible y cuál lo pone en peligro?”.
  • ✂️ Risk storming: sobre los diagramas C4, cada persona marca por separado dónde ve riesgo y con qué probabilidad e impacto; después se comparan las marcas. Las discrepancias son lo más útil.
  • Error común: evaluar la arquitectura contra requisitos que nadie escribió. Sin escenarios, la evaluación es una discusión de gustos.

Laboratorio — Un ATAM reducido sobre Tinkuy

Referencias: el reporte de ATAM; C4: diagramas; MADR. Material: code/week-07/. Dos parejas forman un grupo: una presenta su Tinkuy (con los cambios de las semanas 3 a 6) y la otra evalúa; después cambian.

  1. Antes de la sesión, cada pareja actualiza sus diagramas C4 de contexto y de contenedores, y agrega el de componentes del proceso principal, con el formato de code/week-07/. El script de la carpeta revisa que toda caja tenga descripción y tecnología, y toda flecha verbo y protocolo.
  2. Presentación (10 minutos): objetivos del negocio de Tinkuy, los tres escenarios (A, A) de su utility tree y la arquitectura, usando solo los diagramas.
  3. La pareja que evalúa identifica los enfoques de arquitectura: estilo, división en módulos, dónde están los datos, cómo se llama a la pasarela, qué tácticas hay.
  4. Para cada escenario (A, A), recorrerlo sobre los diagramas: qué elementos intervienen, en qué orden, y qué decisión hace que se cumpla o que no. Registrar en la tabla de code/week-07/ cada riesgo, no riesgo, punto de sensibilidad y punto de trade-off.
  5. Cada persona propone un escenario nuevo que nadie había considerado (un cambio, una falla, un pico). Votar los dos más importantes y recorrerlos también.
  6. Agrupar los riesgos en temas: ¿hay una causa común detrás de varios?
  7. Cambiar de papeles y repetir.
  8. Cada pareja escribe un ADR para el riesgo más grave que le encontraron, con el template de code/week-07/: contexto con el escenario, al menos tres alternativas con lo que cada una gana y cuesta, decisión, consecuencias. La otra pareja lo revisa con una sola pregunta: ¿alguien que no estuvo hoy entendería por qué se decidió así?

Entregas

Sin entregas esta semana. P2 se entrega en la semana 8; sus ADRs siguen el template de este laboratorio.

Preguntas de repaso

  1. ¿Qué preguntas responde cada uno de los tres primeros niveles de C4? ¿Qué lector necesita cada uno?
  2. ¿Qué le falta a este ADR: “Contexto: el catálogo es lento. Decisión: usamos Redis. Consecuencias: es más rápido”? Reescríbanlo.
  3. Hace seis meses se aceptó un ADR que ya no se cumple. ¿Qué se hace con él y por qué no se edita?
  4. En una iteración de ADD, ¿qué se decide primero: la tecnología o los escenarios que se van a atender? ¿Por qué?
  5. Definan riesgo, punto de sensibilidad y punto de trade-off, y den un ejemplo de cada uno en Tinkuy.
  6. ¿Qué puede concluir un equipo después de un ATAM y qué no?

Código de la semana

Compilar y probar dentro del contenedor del curso con make y make test.

Ejemplos (20)Errores (4)Pruebas (4)Laboratorio (1)Compilación (3)

Ejemplos

Los programas que usan los apuntes y la clase.

adr-template.mdDescargar adr-template.md
# ADR 0000: <la decisión, como una frase corta>

<!--
Template de ADR del curso. Copien este archivo a
docs/adr/NNNN-titulo-en-kebab-case.md (NNNN es el siguiente número libre: los
números no se repiten ni se reutilizan), reemplacen cada <indicación> por su
texto y borren estos comentarios si quieren. Revisen la carpeta completa con:

    node /work/code/week-07/check-adr.ts docs/adr

Es el formato de Michael Nygard (título, contexto, decisión, estado,
consecuencias) más las alternativas consideradas. Se escribe en frases
completas, como si le hablaran a quien llegue al equipo dentro de un año. Una
o dos páginas.

Un ADR aceptado no se reescribe. Si la decisión cambia, se escribe otro ADR
que diga en su contexto "Reemplaza al ADR NNNN", y en el anterior solo cambia
la sección Estado.
-->

## Contexto

<!-- Las fuerzas en juego, como hechos y sin opinar todavía: qué pide el
     negocio, qué restricciones hay, qué se midió, qué sabe y qué no sabe el
     equipo. Incluyan el escenario de calidad que empuja la decisión, con su
     medida. Si este ADR reemplaza a otro: "Reemplaza al ADR NNNN" y qué
     cambió desde entonces. -->

<Qué está pasando y por qué hay que decidir algo ahora.>

**Escenario:** <el escenario de calidad, en una o dos frases, con su medida>

## Alternativas consideradas

<!-- La que eligieron y por lo menos dos más. Cada una dice qué gana y qué
     cuesta frente al escenario; las descartadas dicen además por qué no.
     "No hacer nada" casi siempre es una alternativa. -->

### A. <nombre de la alternativa>

- **Gana:** <qué mejora, y para qué atributo de calidad>
- **Cuesta:** <qué empeora o qué obliga a hacer>
- **Por qué no:** <por qué se descartó; la elegida no lleva este ítem>

### B. <nombre de la alternativa>

- **Gana:** <qué mejora>
- **Cuesta:** <qué empeora>
- **Por qué no:** <por qué se descartó>

### C. <nombre de la alternativa>

- **Gana:** <qué mejora>
- **Cuesta:** <qué empeora>
- **Por qué no:** <por qué se descartó>

## Decisión

<!-- En voz activa: "Vamos a...". Cómo responde al escenario del contexto, y
     qué tendría que cambiar para revisarla. -->

- **Alternativa elegida:** <letra>

<Vamos a... porque...>

## Estado

<!-- Una sola línea: Propuesto, Aceptado, Rechazado, Obsoleto o
     "Reemplazado por el ADR NNNN". -->

Propuesto

## Consecuencias

<!-- Todas: lo que queda mejor, lo que queda peor y lo que cambia sin ser
     mejor ni peor. Por lo menos una buena y una mala. -->

- **Buena:** <qué queda mejor>
- **Mala:** <qué queda peor, o qué trabajo nuevo aparece>
- **Neutra:** <qué cambia sin ser mejor ni peor>
adr.tsDescargar adr.ts
// ADR (architecture decision record) con el formato del curso: lee un archivo
// escrito con adr-template.md y comprueba sus reglas. Revisa la forma: que
// estén las secciones, que el contexto nombre el escenario, que haya
// alternativas con lo que cada una gana y cuesta, que el estado sea uno de
// los permitidos y que un ADR reemplazado diga cuál lo reemplaza. No sabe si
// la decisión es buena: eso lo juzga quien lo lee.

import { basename } from 'node:path';
import { type Issue, type Line, fields, normalize, placeholders, prose, readLines, sections, words } from './markdown.ts';

/** Las secciones de un ADR, en el orden en que se escriben. */
export const SECTIONS = ['Contexto', 'Alternativas consideradas', 'Decisión', 'Estado', 'Consecuencias'] as const;
export type SectionName = (typeof SECTIONS)[number];

/** Los estados permitidos. El último lleva el número del ADR que lo reemplaza. */
export const STATUSES = ['Propuesto', 'Aceptado', 'Rechazado', 'Obsoleto', 'Reemplazado por el ADR NNNN'] as const;
export type StatusKind = 'propuesto' | 'aceptado' | 'rechazado' | 'obsoleto' | 'reemplazado';

/** La alternativa elegida y, por lo menos, dos que se descartaron. */
export const MIN_ALTERNATIVES = 3;

export type Alternative = {
  line: number;
  /** La letra con la que se la nombra: A, B, C... */
  letter: string;
  name: string;
  gains: string;
  costs: string;
  /** Por qué se descartó. La elegida no lo lleva. */
  whyNot: string;
};

export type Adr = {
  /** El número del título, con sus cuatro dígitos ("0003"), o '' si no se pudo leer. */
  number: string;
  title: string;
  /** El texto de la línea **Escenario:** del contexto. */
  scenario: string;
  alternatives: Alternative[];
  /** La letra de la alternativa elegida. */
  chosen: string;
  status: StatusKind | '';
  /** Solo si el estado es "Reemplazado por el ADR NNNN". */
  supersededBy: string;
  /** Los ADR que este dice reemplazar ("Reemplaza al ADR NNNN" en el contexto). */
  supersedes: string[];
  consequences: { good: number; bad: number; neutral: number };
};

const TITLE = /^#\s+ADR\s+(\d{4}):\s+(\S.*)$/;
const ALTERNATIVE = /^([A-Z])\.\s+(\S.*)$/;
const SUPERSEDED = /^Reemplazado por el ADR (\d{4})\.?$/i;
const SUPERSEDES = /reemplaza al ADR (\d{4})/gi;

function parseStatus(text: string): { kind: StatusKind | ''; supersededBy: string } {
  const superseded = SUPERSEDED.exec(text);
  if (superseded) return { kind: 'reemplazado', supersededBy: superseded[1]! };
  const plain = normalize(text.replace(/\.$/, ''));
  if (plain === 'propuesto' || plain === 'aceptado' || plain === 'rechazado' || plain === 'obsoleto') {
    return { kind: plain, supersededBy: '' };
  }
  return { kind: '', supersededBy: '' };
}

/** Lee un ADR y devuelve lo que pudo leer y todos sus problemas, ordenados por línea. */
export function checkAdr(text: string): { adr: Adr; issues: Issue[] } {
  const lines = readLines(text);
  const issues: Issue[] = [];
  const adr: Adr = {
    number: '',
    title: '',
    scenario: '',
    alternatives: [],
    chosen: '',
    status: '',
    supersededBy: '',
    supersedes: [],
    consequences: { good: 0, bad: 0, neutral: 0 },
  };

  // Título: "# ADR 0003: Cola de envíos en PostgreSQL".
  const firstHeading = lines.find((line) => /^#{1,6}\s/.test(line.text));
  const title = firstHeading ? TITLE.exec(firstHeading.text) : null;
  if (!firstHeading || !title) {
    issues.push({ line: firstHeading?.number ?? 1, rule: 'titulo', message: 'el archivo empieza con el título "# ADR NNNN: <la decisión>", con el número de cuatro dígitos' });
  } else {
    adr.number = title[1]!;
    adr.title = title[2]!.trim();
    if (/<[^<>]+>/.test(adr.title) || adr.number === '0000') {
      issues.push({ line: firstHeading.number, rule: 'titulo', message: 'el título todavía es el del template: pongan el número del ADR y la decisión' });
    }
  }

  // Secciones: las cinco, una vez cada una y en orden.
  const found = sections(lines, 2);
  const byName = new Map<SectionName, { line: number; body: Line[] }>();
  let lastIndex = -1;
  for (const section of found) {
    const index = SECTIONS.findIndex((name) => normalize(name) === normalize(section.title));
    if (index === -1) {
      issues.push({ line: section.line, rule: 'secciones', message: `la sección "${section.title}" no es del formato: las secciones son ${SECTIONS.join(', ')}` });
      continue;
    }
    const name = SECTIONS[index]!;
    if (byName.has(name)) {
      issues.push({ line: section.line, rule: 'secciones', message: `la sección "${name}" está dos veces` });
      continue;
    }
    if (index < lastIndex) {
      issues.push({ line: section.line, rule: 'secciones', message: `la sección "${name}" está fuera de orden: el orden es ${SECTIONS.join(', ')}` });
    }
    lastIndex = Math.max(lastIndex, index);
    byName.set(name, section);
  }
  for (const name of SECTIONS) {
    const section = byName.get(name);
    if (!section) {
      issues.push({ line: 1, rule: 'secciones', message: `falta la sección "## ${name}"` });
      continue;
    }
    if (prose(section.body) === '') {
      issues.push({ line: section.line, rule: 'vacia', message: `la sección "${name}" está vacía` });
    }
    for (const line of placeholders(section.body)) {
      issues.push({ line: line.number, rule: 'template', message: `quedó texto del template sin reemplazar en "${name}"` });
    }
  }

  // Contexto: nombra el escenario de calidad, con su medida.
  const context = byName.get('Contexto');
  if (context && prose(context.body) !== '') {
    // El escenario es un párrafo: va desde "**Escenario:**" hasta la línea en blanco.
    const start = context.body.findIndex((line) => /\*\*Escenario:\*\*/.test(line.text));
    if (start === -1) {
      issues.push({ line: context.line, rule: 'escenario', message: 'el contexto no nombra el escenario de calidad que empuja la decisión: falta el párrafo "**Escenario:** ..."' });
    } else {
      const paragraph: string[] = [];
      for (let i = start; i < context.body.length && context.body[i]!.text.trim() !== ''; i += 1) {
        paragraph.push(context.body[i]!.text.trim());
      }
      adr.scenario = paragraph.join(' ').replace(/^.*\*\*Escenario:\*\*\s*/, '');
      if (words(adr.scenario).length < 5) {
        issues.push({ line: context.body[start]!.number, rule: 'escenario', message: 'el escenario del contexto está vacío: digan qué llega al sistema, en qué condiciones y con qué medida' });
      } else if (!/\d/.test(adr.scenario)) {
        issues.push({ line: context.body[start]!.number, rule: 'escenario', message: 'el escenario del contexto no tiene medida: sin un número no se puede saber si la decisión lo cumple' });
      }
    }
    adr.supersedes = [...prose(context.body).matchAll(SUPERSEDES)].map((match) => match[1]!);
  }

  // Alternativas: la elegida y al menos dos más, cada una con lo que gana y lo que cuesta.
  const alternatives = byName.get('Alternativas consideradas');
  if (alternatives) {
    const seen = new Set<string>();
    for (const block of sections(alternatives.body, 3)) {
      const match = ALTERNATIVE.exec(block.title);
      if (!match) {
        issues.push({ line: block.line, rule: 'alternativas', message: `"### ${block.title}": una alternativa se titula con su letra y su nombre ("### B. Tabla de trabajos en PostgreSQL")` });
        continue;
      }
      const letter = match[1]!;
      if (seen.has(letter)) {
        issues.push({ line: block.line, rule: 'alternativas', message: `hay dos alternativas con la letra ${letter}` });
        continue;
      }
      seen.add(letter);
      const values = new Map(fields(block.body).map((field) => [field.key, field.value]));
      const alternative: Alternative = {
        line: block.line,
        letter,
        name: match[2]!.trim(),
        gains: values.get('gana') ?? '',
        costs: values.get('cuesta') ?? '',
        whyNot: values.get('por qué no') ?? '',
      };
      adr.alternatives.push(alternative);
      if (words(alternative.gains).length < 3) {
        issues.push({ line: block.line, rule: 'alternativas', message: `la alternativa ${letter} no dice qué gana ("- **Gana:** ...")` });
      }
      if (words(alternative.costs).length < 3) {
        issues.push({ line: block.line, rule: 'alternativas', message: `la alternativa ${letter} no dice qué cuesta ("- **Cuesta:** ..."): toda alternativa cuesta algo, también la elegida` });
      }
    }
    if (adr.alternatives.length < MIN_ALTERNATIVES) {
      issues.push({
        line: alternatives.line,
        rule: 'alternativas',
        message: `hay ${adr.alternatives.length} ${adr.alternatives.length === 1 ? 'alternativa' : 'alternativas'}: hacen falta la elegida y al menos dos que se descartaron`,
      });
    }
  }

  // Decisión: dice cuál de las alternativas se eligió, y por qué.
  const decision = byName.get('Decisión');
  if (decision && prose(decision.body) !== '') {
    const chosen = fields(decision.body).find((field) => field.key === 'alternativa elegida');
    if (!chosen || chosen.value === '') {
      issues.push({ line: decision.line, rule: 'decision', message: 'la decisión no dice cuál alternativa se eligió: falta el ítem "- **Alternativa elegida:** <letra>"' });
    } else {
      const letter = chosen.value.replace(/\.$/, '').trim();
      if (adr.alternatives.some((alternative) => alternative.letter === letter)) {
        adr.chosen = letter;
      } else {
        issues.push({ line: chosen.line, rule: 'decision', message: `la alternativa elegida "${chosen.value}" no es ninguna de las consideradas (${adr.alternatives.map((alternative) => alternative.letter).join(', ') || 'no hay ninguna'})` });
      }
      const reasoning = decision.body.filter((line) => line.number !== chosen.line);
      if (words(prose(reasoning)).length < 10) {
        issues.push({ line: decision.line, rule: 'decision', message: 'la decisión no explica por qué: digan, en frases completas, cómo la alternativa elegida responde al escenario' });
      }
    }
  }
  for (const alternative of adr.alternatives) {
    if (adr.chosen !== '' && alternative.letter !== adr.chosen && words(alternative.whyNot).length < 3) {
      issues.push({ line: alternative.line, rule: 'alternativas', message: `la alternativa ${alternative.letter} se descartó y no dice por qué ("- **Por qué no:** ...")` });
    }
  }

  // Estado: la primera línea de la sección es uno de los estados permitidos.
  const status = byName.get('Estado');
  const statusLine = status?.body.find((line) => line.text.trim() !== '');
  if (status && statusLine) {
    const parsed = parseStatus(statusLine.text.trim());
    adr.status = parsed.kind;
    adr.supersededBy = parsed.supersededBy;
    if (parsed.kind === '') {
      issues.push({ line: statusLine.number, rule: 'estado', message: `el estado "${statusLine.text.trim()}" no existe: es ${STATUSES.join(', ')}` });
    } else if (parsed.kind === 'reemplazado' && parsed.supersededBy === adr.number) {
      issues.push({ line: statusLine.number, rule: 'reemplazo', message: 'un ADR no se reemplaza a sí mismo' });
    }
  }

  // Consecuencias: todas, no solo las buenas.
  const consequences = byName.get('Consecuencias');
  if (consequences && prose(consequences.body) !== '') {
    for (const field of fields(consequences.body)) {
      if (field.key === 'buena') adr.consequences.good += 1;
      else if (field.key === 'mala') adr.consequences.bad += 1;
      else if (field.key === 'neutra') adr.consequences.neutral += 1;
    }
    if (adr.consequences.good === 0) {
      issues.push({ line: consequences.line, rule: 'consecuencias', message: 'no hay ninguna consecuencia buena ("- **Buena:** ..."): si la decisión no mejora nada, ¿para qué se tomó?' });
    }
    if (adr.consequences.bad === 0) {
      issues.push({ line: consequences.line, rule: 'consecuencias', message: 'no hay ninguna consecuencia mala ("- **Mala:** ..."): toda decisión de arquitectura cuesta algo, y el ADR lo dice' });
    }
  }

  issues.sort((a, b) => a.line - b.line);
  return { adr, issues };
}

export type NamedAdr = { file: string; adr: Adr };
export type SetIssue = { file: string; rule: string; message: string };

/**
 * Las reglas que solo se pueden revisar con todos los ADR juntos: la
 * numeración y los reemplazos. Un ADR reemplazado apunta a otro que existe,
 * que es posterior, que ya fue aceptado y que dice a quién reemplaza.
 */
export function checkSet(adrs: NamedAdr[]): SetIssue[] {
  const issues: SetIssue[] = [];
  const byNumber = new Map<string, NamedAdr>();

  for (const entry of adrs) {
    const { adr, file } = entry;
    if (adr.number === '') continue;

    const inName = /^(\d{4})-/.exec(basename(file));
    if (!inName) {
      issues.push({ file, rule: 'numeracion', message: `el archivo se llama NNNN-titulo-en-kebab-case.md, con el número del ADR (${adr.number})` });
    } else if (inName[1] !== adr.number) {
      issues.push({ file, rule: 'numeracion', message: `el nombre del archivo dice ${inName[1]} y el título dice ADR ${adr.number}` });
    }

    const previous = byNumber.get(adr.number);
    if (previous) {
      issues.push({ file, rule: 'numeracion', message: `el número ${adr.number} ya lo usa ${previous.file}: los números no se repiten ni se reutilizan` });
    } else {
      byNumber.set(adr.number, entry);
    }
  }

  for (const { adr, file } of adrs) {
    if (adr.status === 'reemplazado' && adr.supersededBy !== adr.number) {
      const replacement = byNumber.get(adr.supersededBy);
      if (!replacement) {
        issues.push({ file, rule: 'reemplazo', message: `dice que lo reemplaza el ADR ${adr.supersededBy}, que no está entre los archivos revisados` });
      } else {
        if (Number(adr.supersededBy) < Number(adr.number)) {
          issues.push({ file, rule: 'reemplazo', message: `lo reemplaza el ADR ${adr.supersededBy}, que es anterior: quien reemplaza se escribe después` });
        }
        if (replacement.adr.status !== 'aceptado' && replacement.adr.status !== 'reemplazado') {
          issues.push({ file, rule: 'reemplazo', message: `el ADR ${adr.supersededBy} todavía no fue aceptado: mientras tanto, este sigue vigente y su estado no cambia` });
        }
        if (!replacement.adr.supersedes.includes(adr.number)) {
          issues.push({ file: replacement.file, rule: 'reemplazo', message: `el ADR ${adr.number} dice que este lo reemplaza, y aquí el contexto no lo dice ("Reemplaza al ADR ${adr.number}")` });
        }
      }
    }

    // Al revés: un ADR aceptado que dice reemplazar a otro, y el otro no se enteró.
    if (adr.status === 'aceptado') {
      for (const number of adr.supersedes) {
        const replaced = byNumber.get(number);
        if (replaced && !(replaced.adr.status === 'reemplazado' && replaced.adr.supersededBy === adr.number)) {
          issues.push({ file: replaced.file, rule: 'reemplazo', message: `el ADR ${adr.number} fue aceptado y dice que reemplaza a este: aquí el estado debe ser "Reemplazado por el ADR ${adr.number}"` });
        }
      }
    }
  }
  return issues;
}

/** El estado, como se escribe en el archivo. */
export function statusText(adr: Adr): string {
  switch (adr.status) {
    case 'propuesto':
      return 'Propuesto';
    case 'aceptado':
      return 'Aceptado';
    case 'rechazado':
      return 'Rechazado';
    case 'obsoleto':
      return 'Obsoleto';
    case 'reemplazado':
      return `Reemplazado por el ADR ${adr.supersededBy}`;
    default:
      return 'estado desconocido';
  }
}
arc42-template.mdDescargar arc42-template.md
# Arquitectura de <sistema>

<!--
Esqueleto con las doce secciones de arc42 (https://docs.arc42.org/home/). No
hay que llenarlas todas: llenen las que alguien va a leer y, en las demás,
digan en una línea por qué todavía no. Lo que ya está en otro archivo del
repositorio (diagramas, ADR, escenarios) se enlaza, no se copia. Revisen con:

    node /work/code/week-07/arc42.ts docs/arc42.md
-->

## 1. Introducción y objetivos

<Qué hace el sistema, para quién, y sus tres o cuatro objetivos de calidad más importantes. Los stakeholders y qué espera cada uno.>

## 2. Restricciones

<Lo que no se puede decidir: tecnología impuesta, plazos, normas, presupuesto, convenciones del equipo.>

## 3. Contexto y alcance

<El diagrama de contexto: personas, sistemas externos y lo que viaja por cada interfaz.>

## 4. Estrategia de solución

<Las pocas decisiones que dan forma a todo lo demás: estilo, tecnología principal, cómo se atiende cada objetivo de calidad.>

## 5. Vista de bloques

<La descomposición estática: contenedores y, donde haga falta, componentes.>

## 6. Vista de ejecución

<Cómo colaboran los bloques en los casos que importan: el camino principal, y los que tienen que ver con fallas o con carga.>

## 7. Vista de despliegue

<En qué máquinas o entornos corre cada bloque.>

## 8. Conceptos transversales

<Las reglas que valen para todo el sistema: manejo de errores, sesiones, logs, convenciones de la base de datos.>

## 9. Decisiones de arquitectura

<La lista de los ADR, con su estado.>

## 10. Requisitos de calidad

<El utility tree y los escenarios de calidad.>

## 11. Riesgos y deuda técnica

<Los riesgos conocidos (por ejemplo, los de la última evaluación) y lo que se sabe que hay que pagar.>

## 12. Glosario

<Los términos del negocio y del equipo que alguien de fuera no entendería.>
arc42.tsDescargar arc42.ts
// Las doce secciones de arc42, en su orden, y un revisor para un documento
// que las sigue. arc42 es un template para el documento de arquitectura
// completo: https://docs.arc42.org/home/
//
//   node arc42.ts docs/arc42.md
//
// El revisor comprueba que estén las doce, numeradas y en orden, y que
// ninguna esté vacía. Una sección que el equipo decide no llenar lo dice en
// una línea ("No se documenta todavía: ..."): eso también es contenido.

import { readFileSync } from 'node:fs';
import { pathToFileURL } from 'node:url';
import { type Issue, normalize, placeholders, prose, readLines, sections } from './markdown.ts';

export const ARC42_SECTIONS = [
  { number: 1, name: 'Introducción y objetivos', english: 'Introduction and Goals' },
  { number: 2, name: 'Restricciones', english: 'Constraints' },
  { number: 3, name: 'Contexto y alcance', english: 'Context and Scope' },
  { number: 4, name: 'Estrategia de solución', english: 'Solution Strategy' },
  { number: 5, name: 'Vista de bloques', english: 'Building Block View' },
  { number: 6, name: 'Vista de ejecución', english: 'Runtime View' },
  { number: 7, name: 'Vista de despliegue', english: 'Deployment View' },
  { number: 8, name: 'Conceptos transversales', english: 'Crosscutting Concepts' },
  { number: 9, name: 'Decisiones de arquitectura', english: 'Architecture Decisions' },
  { number: 10, name: 'Requisitos de calidad', english: 'Quality Requirements' },
  { number: 11, name: 'Riesgos y deuda técnica', english: 'Risks and Technical Debt' },
  { number: 12, name: 'Glosario', english: 'Glossary' },
] as const;

/** Revisa que el documento tenga las doce secciones (`## N. Nombre`), en orden y con contenido. */
export function checkOutline(text: string): Issue[] {
  const issues: Issue[] = [];
  const found = sections(readLines(text), 2);
  let position = 0;

  for (const expected of ARC42_SECTIONS) {
    const title = `${expected.number}. ${expected.name}`;
    const index = found.findIndex((section) => normalize(section.title) === normalize(title));
    if (index === -1) {
      issues.push({ line: 1, rule: 'secciones', message: `falta la sección "## ${title}" (${expected.english})` });
      continue;
    }
    const section = found[index]!;
    if (index < position) {
      issues.push({ line: section.line, rule: 'secciones', message: `"${title}" está fuera de orden` });
    }
    position = Math.max(position, index);
    if (prose(section.body) === '') {
      issues.push({ line: section.line, rule: 'vacia', message: `"${title}" está vacía: si no se va a llenar, digan en una línea por qué` });
    }
    for (const line of placeholders(section.body)) {
      issues.push({ line: line.number, rule: 'template', message: `quedó texto del template sin reemplazar en "${title}"` });
    }
  }

  const known = new Set(ARC42_SECTIONS.map((section) => normalize(`${section.number}. ${section.name}`)));
  for (const section of found) {
    if (!known.has(normalize(section.title))) {
      issues.push({ line: section.line, rule: 'secciones', message: `"${section.title}" no es una de las doce secciones de arc42` });
    }
  }

  issues.sort((a, b) => a.line - b.line);
  return issues;
}

function main(files: string[]): number {
  if (files.length === 0) {
    console.error('Uso: node arc42.ts <documento.md>');
    return 2;
  }
  let errors = 0;
  for (const file of files) {
    let text: string;
    try {
      text = readFileSync(file, 'utf8');
    } catch {
      console.error(`${file}: no se pudo leer el archivo`);
      return 2;
    }
    const issues = checkOutline(text);
    for (const issue of issues) console.log(`${file}:${issue.line}: [${issue.rule}] ${issue.message}`);
    console.log(`${file}: ${issues.length === 0 ? 'las doce secciones de arc42, sin errores' : `${issues.length} ${issues.length === 1 ? 'error' : 'errores'}`}`);
    errors += issues.length;
  }
  return errors === 0 ? 0 : 1;
}

if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
  process.exitCode = main(process.argv.slice(2));
}
atam-template.mdDescargar atam-template.md
# ATAM reducido de <sistema>

<!--
Tabla del laboratorio de la semana 7. La llena la pareja que evalúa, mientras
la otra presenta. Guárdenla como docs/atam.md en el repositorio de quien fue
evaluado y revísenla con:

    node /work/code/week-07/check-atam.ts docs/atam.md

Un ejemplo lleno, de otro sistema: example/yupana/docs/atam.md.
-->

- Sistema: <nombre>
- Presenta: <quiénes diseñaron>
- Evalúa: <quiénes preguntan>

## Objetivos del negocio

<!-- Paso 2 del método: para qué existe el sistema, en palabras de quien lo
     paga. Dos a cuatro. Los temas de riesgo se comparan contra esta lista. -->

- <objetivo>

## Enfoques de arquitectura

<!-- Paso 4: el estilo, la división en módulos, dónde están los datos, cómo
     se llama a cada sistema externo, qué tácticas hay. Aquí solo se listan:
     todavía no se analizan. Identificadores A1, A2... -->

| Id | Enfoque | Dónde se ve |
|---|---|---|
| A1 | <estilo, táctica o decisión> | <diagrama, y elemento o relación> |

## Escenarios

<!-- Los escenarios (A, A) del utility tree (paso 5) y los más votados de la
     lluvia de ideas (paso 7). El resumen lleva su medida. Origen: "utility
     tree (A, A)" o "lluvia de ideas (N votos)". Identificadores E1, E2... -->

| Id | Escenario | Atributo | Origen |
|---|---|---|---|
| E1 | <estímulo, entorno y medida de la respuesta> | <atributo de calidad> | utility tree (A, A) |

## Hallazgos

<!-- Pasos 6 y 8: lo que aparece al recorrer cada escenario sobre los
     diagramas. Una fila por decisión.

     Tipo                    Id   Qué es
     riesgo                  R1   una decisión (o una que falta tomar) que puede impedir el escenario
     no riesgo               N1   una decisión que se analizó y está bien; el razonamiento dice bajo qué supuesto
     punto de sensibilidad   S1   una propiedad de la que depende mucho la respuesta de un atributo
     punto de trade-off      T1   una propiedad que es punto de sensibilidad de dos atributos o más

     "Decisión" nombra la decisión, no el síntoma: "los pedidos se atienden
     en un solo proceso", no "el sistema podría caerse". "Razonamiento" une
     la decisión con la respuesta del escenario, con una cuenta si se puede. -->

| Id | Tipo | Escenarios | Enfoques | Decisión | Atributos | Razonamiento |
|---|---|---|---|---|---|---|
| R1 | riesgo | E1 | A1 | <la decisión> | <atributo> | <por qué puede impedir el escenario> |

## Temas de riesgo

<!-- Paso 9: lo que varios riesgos tienen en común, y qué objetivo del
     negocio amenaza cada tema. Si los riesgos no comparten causa, la tabla
     queda sin filas. -->

| Tema | Riesgos | Objetivo del negocio que amenaza |
|---|---|---|
| <la causa común, en una frase> | R1, R2 | <cuál de los objetivos de arriba> |
atam.tsDescargar atam.ts
// La tabla de un ATAM reducido, con el formato de atam-template.md: enfoques
// de arquitectura, escenarios, hallazgos (riesgos, no riesgos, puntos de
// sensibilidad y puntos de trade-off) y temas de riesgo. El revisor comprueba
// que cada hallazgo esté completo y bien clasificado por su forma. No sabe si
// el razonamiento es correcto: eso lo discuten las dos parejas.

import { type Issue, type Line, firstTable, idList, normalize, placeholders, readLines, sameColumns, sections, words } from './markdown.ts';

/** Los cuatro tipos de hallazgo, con la letra con la que empieza su identificador. */
export const FINDING_KINDS = {
  riesgo: 'R',
  'no riesgo': 'N',
  'punto de sensibilidad': 'S',
  'punto de trade-off': 'T',
} as const;
export type FindingKind = keyof typeof FINDING_KINDS;

export const ORIGINS = ['utility tree', 'lluvia de ideas'] as const;

export const APPROACH_COLUMNS = ['Id', 'Enfoque', 'Dónde se ve'] as const;
export const SCENARIO_COLUMNS = ['Id', 'Escenario', 'Atributo', 'Origen'] as const;
export const FINDING_COLUMNS = ['Id', 'Tipo', 'Escenarios', 'Enfoques', 'Decisión', 'Atributos', 'Razonamiento'] as const;
export const THEME_COLUMNS = ['Tema', 'Riesgos', 'Objetivo del negocio que amenaza'] as const;

const SECTION_NAMES = ['Objetivos del negocio', 'Enfoques de arquitectura', 'Escenarios', 'Hallazgos', 'Temas de riesgo'] as const;

export type Approach = { line: number; id: string; text: string; where: string };
export type Scenario = { line: number; id: string; text: string; attribute: string; origin: string };
export type Finding = {
  line: number;
  id: string;
  kind: string;
  scenarios: string[];
  approaches: string[];
  decision: string;
  attributes: string[];
  reasoning: string;
};
export type Theme = { line: number; name: string; risks: string[]; goal: string };

export type Evaluation = {
  system: string;
  goals: string[];
  approaches: Approach[];
  scenarios: Scenario[];
  findings: Finding[];
  themes: Theme[];
};

function isKind(kind: string): kind is FindingKind {
  return Object.hasOwn(FINDING_KINDS, kind);
}

type Row = { line: number; cells: string[] };

/** Las filas de la tabla de una sección, si la tabla existe y tiene las columnas del formato. */
function tableRows(section: { line: number; body: Line[] } | undefined, name: string, columns: readonly string[], issues: Issue[]): Row[] {
  if (!section) return [];
  const table = firstTable(section.body);
  if (!table) {
    issues.push({ line: section.line, rule: 'secciones', message: `la sección "${name}" no tiene su tabla` });
    return [];
  }
  if (!sameColumns(table.header, columns)) {
    issues.push({ line: table.headerLine, rule: 'secciones', message: `las columnas de "${name}" son: ${columns.join(' | ')}` });
    return [];
  }
  const rows: Row[] = [];
  for (const row of table.rows) {
    if (row.cells.length !== columns.length) {
      issues.push({ line: row.line, rule: 'secciones', message: `la fila tiene ${row.cells.length} celdas y debe tener ${columns.length}` });
    } else {
      rows.push(row);
    }
  }
  return rows;
}

/** Lee la tabla de un ATAM reducido y devuelve lo que pudo leer y sus problemas, ordenados por línea. */
export function checkEvaluation(text: string): { evaluation: Evaluation; issues: Issue[] } {
  const lines = readLines(text);
  const issues: Issue[] = [];
  const evaluation: Evaluation = { system: '', goals: [], approaches: [], scenarios: [], findings: [], themes: [] };

  const system = lines.map((line) => /^\s*(?:[-*]\s+)?Sistema\s*:\s*(.*)$/i.exec(line.text)).find((match) => match !== null);
  if (!system || system[1]!.trim() === '') {
    issues.push({ line: 1, rule: 'sistema', message: 'falta la línea "Sistema: ..." con el nombre del sistema que se evalúa' });
  } else {
    evaluation.system = system[1]!.trim();
  }

  const byName = new Map<string, { line: number; body: Line[] }>();
  for (const section of sections(lines, 2)) byName.set(normalize(section.title), section);
  for (const name of SECTION_NAMES) {
    const section = byName.get(normalize(name));
    if (!section) {
      issues.push({ line: 1, rule: 'secciones', message: `falta la sección "## ${name}"` });
      continue;
    }
    for (const line of placeholders(section.body)) {
      issues.push({ line: line.number, rule: 'template', message: `quedó texto del template sin reemplazar en "${name}"` });
    }
  }

  // Objetivos del negocio: una lista. Sin ellos no se puede decir qué amenaza un riesgo.
  const goals = byName.get(normalize('Objetivos del negocio'));
  if (goals) {
    evaluation.goals = goals.body
      .map((line) => /^\s*(?:[-*]|\d+\.)\s+(\S.*)$/.exec(line.text)?.[1]?.trim() ?? '')
      .filter((goal) => goal !== '');
    if (evaluation.goals.length === 0) {
      issues.push({ line: goals.line, rule: 'objetivos', message: 'no hay ningún objetivo del negocio: la evaluación empieza por saber para qué existe el sistema' });
    }
  }

  // Los identificadores no se repiten en todo el archivo.
  const ids = new Map<string, number>();
  const claim = (id: string, line: number, pattern: RegExp, shape: string): boolean => {
    if (!pattern.test(id)) {
      issues.push({ line, rule: 'id', message: `"${id}" no es un identificador válido aquí: se escribe ${shape}` });
      return false;
    }
    const previous = ids.get(id);
    if (previous !== undefined) {
      issues.push({ line, rule: 'id', message: `el identificador ${id} ya está en la línea ${previous}` });
      return false;
    }
    ids.set(id, line);
    return true;
  };

  for (const row of tableRows(byName.get(normalize('Enfoques de arquitectura')), 'Enfoques de arquitectura', APPROACH_COLUMNS, issues)) {
    const [id, text, where] = row.cells as [string, string, string];
    if (!claim(id, row.line, /^A\d+$/, 'A1, A2...')) continue;
    evaluation.approaches.push({ line: row.line, id, text, where });
    if (words(text).length < 3) {
      issues.push({ line: row.line, rule: 'enfoque', message: `${id} no dice cuál es el enfoque: un estilo, una táctica o una decisión, con sus palabras` });
    }
    if (words(where).length < 2) {
      issues.push({ line: row.line, rule: 'enfoque', message: `${id} no dice dónde se ve: en qué diagrama y en qué elemento o relación` });
    }
  }
  if (byName.has(normalize('Enfoques de arquitectura')) && evaluation.approaches.length === 0) {
    issues.push({ line: byName.get(normalize('Enfoques de arquitectura'))!.line, rule: 'enfoque', message: 'no hay ningún enfoque de arquitectura identificado' });
  }

  for (const row of tableRows(byName.get(normalize('Escenarios')), 'Escenarios', SCENARIO_COLUMNS, issues)) {
    const [id, text, attribute, origin] = row.cells as [string, string, string, string];
    if (!claim(id, row.line, /^E\d+$/, 'E1, E2...')) continue;
    evaluation.scenarios.push({ line: row.line, id, text, attribute, origin });
    if (!/\d/.test(text)) {
      issues.push({ line: row.line, rule: 'escenario', message: `${id} no tiene medida: sin un número, el recorrido no puede decir si se cumple` });
    }
    if (words(attribute).length === 0) {
      issues.push({ line: row.line, rule: 'escenario', message: `${id} no dice de qué atributo de calidad es` });
    }
    if (!ORIGINS.some((known) => normalize(origin).startsWith(known))) {
      issues.push({ line: row.line, rule: 'origen', message: `${id}: el origen es "${ORIGINS[0]}" (con sus dos notas) o "${ORIGINS[1]}" (con sus votos)` });
    }
  }
  if (byName.has(normalize('Escenarios'))) {
    for (const origin of ORIGINS) {
      if (!evaluation.scenarios.some((scenario) => normalize(scenario.origin).startsWith(origin))) {
        issues.push({ line: byName.get(normalize('Escenarios'))!.line, rule: 'origen', message: `no hay ningún escenario con origen "${origin}"` });
      }
    }
  }

  const approachIds = new Set(evaluation.approaches.map((approach) => approach.id));
  const scenarioIds = new Set(evaluation.scenarios.map((scenario) => scenario.id));

  for (const row of tableRows(byName.get(normalize('Hallazgos')), 'Hallazgos', FINDING_COLUMNS, issues)) {
    const [id, kindCell, scenariosCell, approachesCell, decision, attributesCell, reasoning] = row.cells as [string, string, string, string, string, string, string];
    const kind = normalize(kindCell);
    const finding: Finding = {
      line: row.line,
      id,
      kind,
      scenarios: idList(scenariosCell),
      approaches: idList(approachesCell),
      decision,
      attributes: [...new Set(idList(attributesCell).map(normalize))],
      reasoning,
    };

    if (!isKind(kind)) {
      issues.push({ line: row.line, rule: 'tipo', message: `${id}: el tipo "${kindCell}" no existe; es ${Object.keys(FINDING_KINDS).join(', ')}` });
      claim(id, row.line, /^[A-Z]\d+$/, 'una letra y un número');
    } else if (!claim(id, row.line, new RegExp(`^${FINDING_KINDS[kind]}\\d+$`), `${FINDING_KINDS[kind]}1, ${FINDING_KINDS[kind]}2... para un ${kind}`)) {
      continue;
    }
    evaluation.findings.push(finding);

    if (finding.scenarios.length === 0) {
      issues.push({ line: row.line, rule: 'escenario', message: `${id} no dice al recorrer qué escenario apareció` });
    }
    for (const scenario of finding.scenarios) {
      if (!scenarioIds.has(scenario)) {
        issues.push({ line: row.line, rule: 'escenario', message: `${id}: "${scenario}" no está en la tabla de Escenarios` });
      }
    }
    if (finding.approaches.length === 0) {
      issues.push({ line: row.line, rule: 'enfoque', message: `${id} no dice a qué enfoque de arquitectura pertenece la decisión` });
    }
    for (const approach of finding.approaches) {
      if (!approachIds.has(approach)) {
        issues.push({ line: row.line, rule: 'enfoque', message: `${id}: "${approach}" no está en la tabla de Enfoques de arquitectura` });
      }
    }
    if (words(decision).length < 4) {
      issues.push({ line: row.line, rule: 'decision', message: `${id} no nombra una decisión de arquitectura: qué se decidió (o qué falta decidir), no qué podría salir mal` });
    }
    if (finding.attributes.length === 0) {
      issues.push({ line: row.line, rule: 'atributos', message: `${id} no dice a qué atributo de calidad afecta` });
    } else if (kind === 'punto de trade-off' && finding.attributes.length < 2) {
      issues.push({ line: row.line, rule: 'atributos', message: `${id} es un punto de trade-off y nombra un solo atributo: un trade-off afecta por lo menos a dos; con uno es un punto de sensibilidad` });
    }
    if (words(reasoning).length < 8) {
      issues.push({ line: row.line, rule: 'razonamiento', message: `${id} no explica por qué: el razonamiento une la decisión con la respuesta del escenario` });
    }
  }

  // Un escenario que se recorrió deja al menos un hallazgo, aunque sea un no riesgo.
  for (const scenario of evaluation.scenarios) {
    if (!evaluation.findings.some((finding) => finding.scenarios.includes(scenario.id))) {
      issues.push({ line: scenario.line, rule: 'sin-analizar', message: `${scenario.id} no tiene ningún hallazgo: si se recorrió y todo está bien, eso es un no riesgo, y se anota con su supuesto` });
    }
  }

  const riskIds = new Set(evaluation.findings.filter((finding) => finding.kind === 'riesgo').map((finding) => finding.id));
  for (const row of tableRows(byName.get(normalize('Temas de riesgo')), 'Temas de riesgo', THEME_COLUMNS, issues)) {
    const [name, risksCell, goal] = row.cells as [string, string, string];
    const theme: Theme = { line: row.line, name, risks: idList(risksCell), goal };
    evaluation.themes.push(theme);
    if (words(name).length < 3) {
      issues.push({ line: row.line, rule: 'tema', message: 'el tema no dice qué tienen en común sus riesgos' });
    }
    for (const risk of theme.risks) {
      if (!riskIds.has(risk)) {
        issues.push({ line: row.line, rule: 'tema', message: `"${risk}" no es un riesgo de la tabla de Hallazgos: un tema agrupa riesgos` });
      }
    }
    if (new Set(theme.risks.filter((risk) => riskIds.has(risk))).size < 2) {
      issues.push({ line: row.line, rule: 'tema', message: `"${name}" agrupa menos de dos riesgos: un tema es lo que varios riesgos tienen en común` });
    }
    if (words(goal).length < 3) {
      issues.push({ line: row.line, rule: 'tema', message: `"${name}" no dice qué objetivo del negocio amenaza` });
    }
  }

  issues.sort((a, b) => a.line - b.line);
  return { evaluation, issues };
}

/** Cuántos hallazgos hay de cada tipo. */
export function countByKind(evaluation: Evaluation): Record<FindingKind, number> {
  const counts: Record<FindingKind, number> = { riesgo: 0, 'no riesgo': 0, 'punto de sensibilidad': 0, 'punto de trade-off': 0 };
  for (const finding of evaluation.findings) {
    if (isKind(finding.kind)) counts[finding.kind] += 1;
  }
  return counts;
}
check-adr.tsDescargar check-adr.ts
// Revisa uno o más ADR escritos con adr-template.md.
//
//   node check-adr.ts docs/adr                      todos los NNNN-*.md de la carpeta
//   node check-adr.ts docs/adr/0003-cola.md ...     los archivos que se le pasen
//
// Los reemplazos entre ADR solo se pueden revisar si se le pasan todos juntos
// (o la carpeta). Termina con código 0 si no encontró errores, 1 si encontró
// alguno y 2 si no pudo leer un archivo o no recibió ninguno.

import { readFileSync, readdirSync, statSync } from 'node:fs';
import { join } from 'node:path';
import { checkAdr, checkSet, statusText, type NamedAdr } from './adr.ts';

function plural(count: number, one: string, many: string): string {
  return `${count} ${count === 1 ? one : many}`;
}

/** Una carpeta se cambia por sus archivos de ADR, en orden. */
function expand(paths: string[]): string[] {
  return paths.flatMap((path) => {
    if (!statSync(path).isDirectory()) return [path];
    return readdirSync(path)
      .filter((name) => /^\d{4}-.*\.md$/.test(name))
      .sort()
      .map((name) => join(path, name));
  });
}

function main(args: string[]): number {
  let files: string[];
  try {
    files = expand(args);
  } catch {
    console.error('No se pudo leer alguno de los archivos o carpetas');
    return 2;
  }
  if (files.length === 0) {
    console.error('Uso: node check-adr.ts <carpeta de ADR> | <adr.md> [<otro-adr.md> ...]');
    return 2;
  }

  let errors = 0;
  const read: NamedAdr[] = [];

  for (const file of files) {
    let text: string;
    try {
      text = readFileSync(file, 'utf8');
    } catch {
      console.error(`${file}: no se pudo leer el archivo`);
      return 2;
    }

    const { adr, issues } = checkAdr(text);
    read.push({ file, adr });
    for (const issue of issues) {
      console.log(`${file}:${issue.line}: [${issue.rule}] ${issue.message}`);
    }

    const chosen = adr.chosen === '' ? 'sin elegida' : `elegida: ${adr.chosen}`;
    const summary = `ADR ${adr.number || '????'}, ${statusText(adr)}, ${plural(adr.alternatives.length, 'alternativa', 'alternativas')} (${chosen})`;
    console.log(`${file}: ${summary}: ${issues.length === 0 ? 'sin errores' : plural(issues.length, 'error', 'errores')}`);
    errors += issues.length;
  }

  for (const issue of checkSet(read)) {
    console.log(`${issue.file}: [${issue.rule}] ${issue.message}`);
    errors += 1;
  }

  return errors === 0 ? 0 : 1;
}

process.exitCode = main(process.argv.slice(2));
check-atam.tsDescargar check-atam.ts
// Revisa la tabla de un ATAM reducido escrita con atam-template.md.
//
//   node check-atam.ts docs/atam.md
//
// Termina con código 0 si no encontró errores, 1 si encontró alguno y 2 si no
// pudo leer un archivo o no recibió ninguno.

import { readFileSync } from 'node:fs';
import { checkEvaluation, countByKind } from './atam.ts';

function plural(count: number, one: string, many: string): string {
  return `${count} ${count === 1 ? one : many}`;
}

function main(files: string[]): number {
  if (files.length === 0) {
    console.error('Uso: node check-atam.ts <atam.md> [<otro-atam.md> ...]');
    return 2;
  }

  let errors = 0;
  for (const file of files) {
    let text: string;
    try {
      text = readFileSync(file, 'utf8');
    } catch {
      console.error(`${file}: no se pudo leer el archivo`);
      return 2;
    }

    const { evaluation, issues } = checkEvaluation(text);
    for (const issue of issues) {
      console.log(`${file}:${issue.line}: [${issue.rule}] ${issue.message}`);
    }

    const counts = countByKind(evaluation);
    const summary = [
      `ATAM de ${evaluation.system || '(sin sistema)'}`,
      plural(evaluation.approaches.length, 'enfoque', 'enfoques'),
      plural(evaluation.scenarios.length, 'escenario', 'escenarios'),
      plural(counts.riesgo, 'riesgo', 'riesgos'),
      plural(counts['no riesgo'], 'no riesgo', 'no riesgos'),
      plural(counts['punto de sensibilidad'], 'punto de sensibilidad', 'puntos de sensibilidad'),
      plural(counts['punto de trade-off'], 'punto de trade-off', 'puntos de trade-off'),
      plural(evaluation.themes.length, 'tema de riesgo', 'temas de riesgo'),
    ].join(', ');
    console.log(`${file}: ${summary}: ${issues.length === 0 ? 'sin errores' : plural(issues.length, 'error', 'errores')}`);
    errors += issues.length;
  }

  return errors === 0 ? 0 : 1;
}

process.exitCode = main(process.argv.slice(2));
markdown.tsDescargar markdown.ts
// Lo mínimo de Markdown que necesitan los revisores de la semana: partir un
// archivo en secciones, leer una tabla y leer los ítems `- **Clave:** valor`.

export type Line = { number: number; text: string };

export type Section = {
  /** Título sin los `#`. */
  title: string;
  /** Línea del título, contando desde 1. */
  line: number;
  /** Las líneas que siguen al título, hasta el próximo título del mismo nivel o de uno superior. */
  body: Line[];
};

export type Issue = { line: number; rule: string; message: string };

export type Table = { headerLine: number; header: string[]; rows: { line: number; cells: string[] }[] };

/** Para comparar textos: sin espacios de más y sin distinguir mayúsculas. */
export function normalize(text: string): string {
  return text.trim().replace(/\s+/g, ' ').toLocaleLowerCase('es');
}

/** Las palabras de un texto (lo que tiene al menos una letra o un número). */
export function words(text: string): string[] {
  return text.trim().split(/\s+/).filter((word) => /[\p{L}\p{N}]/u.test(word));
}

/**
 * Las líneas de un archivo, sin los comentarios HTML (`<!-- ... -->`), que es
 * donde los templates llevan sus instrucciones. Los números de línea se
 * conservan: una línea que era solo comentario queda vacía.
 */
export function readLines(text: string): Line[] {
  const withoutComments = text.replace(/<!--[\s\S]*?-->/g, (comment) => comment.replace(/[^\n]/g, ''));
  return withoutComments.split(/\r?\n/).map((line, index) => ({ number: index + 1, text: line }));
}

/** Las secciones de un nivel (`##` es el nivel 2). */
export function sections(lines: Line[], level: number): Section[] {
  const heading = new RegExp(`^#{${level}}\\s+(.*)$`);
  const stop = new RegExp(`^#{1,${level}}\\s`);
  const found: Section[] = [];
  let current: Section | undefined;

  for (const line of lines) {
    const match = heading.exec(line.text);
    if (match) {
      current = { title: match[1]!.trim(), line: line.number, body: [] };
      found.push(current);
    } else if (stop.test(line.text)) {
      current = undefined;
    } else if (current) {
      current.body.push(line);
    }
  }
  return found;
}

/** El texto de una sección, sin títulos de niveles inferiores ni líneas vacías. */
export function prose(body: Line[]): string {
  return body
    .map((line) => line.text.trim())
    .filter((text) => text !== '' && !/^#{1,6}\s/.test(text))
    .join(' ');
}

/** Lo que quedó sin llenar de un template: un `<texto entre ángulos>`. */
export function placeholders(body: Line[]): Line[] {
  return body.filter((line) => /<[^<>\n]{3,}>/.test(line.text));
}

export type Field = { line: number; key: string; value: string };

/**
 * Los ítems `- **Clave:** valor` de un bloque. El valor sigue en las líneas
 * de abajo mientras tengan sangría y no empiecen otro ítem.
 */
export function fields(body: Line[]): Field[] {
  const item = /^\s*[-*]\s+\*\*([^*:]+):\*\*\s*(.*)$/;
  const found: Field[] = [];
  let open: Field | undefined;

  for (const line of body) {
    const match = item.exec(line.text);
    if (match) {
      open = { line: line.number, key: normalize(match[1]!), value: match[2]!.trim() };
      found.push(open);
    } else if (open && /^\s+\S/.test(line.text) && !/^\s*[-*]\s/.test(line.text)) {
      open.value = `${open.value} ${line.text.trim()}`.trim();
    } else {
      open = undefined;
    }
  }
  return found;
}

function splitRow(line: string): string[] {
  const inner = line.trim().replace(/^\|/, '').replace(/\|$/, '');
  return inner.split(/(?<!\\)\|/).map((cell) => cell.replace(/\\\|/g, '|').trim());
}

function isSeparatorRow(line: string): boolean {
  return /^\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?$/.test(line.trim());
}

/** La primera tabla de un bloque, si tiene alguna. */
export function firstTable(body: Line[]): Table | undefined {
  const start = body.findIndex((line) => line.text.trim().startsWith('|'));
  if (start === -1) return undefined;

  const table: Table = { headerLine: body[start]!.number, header: splitRow(body[start]!.text), rows: [] };
  for (let i = start + 1; i < body.length && body[i]!.text.trim().startsWith('|'); i += 1) {
    if (isSeparatorRow(body[i]!.text)) continue;
    table.rows.push({ line: body[i]!.number, cells: splitRow(body[i]!.text) });
  }
  return table;
}

/** `true` si la cabecera de la tabla es exactamente la esperada. */
export function sameColumns(header: string[], expected: readonly string[]): boolean {
  return header.length === expected.length && header.every((cell, i) => normalize(cell) === normalize(expected[i]!));
}

/** Parte una celda como "R1, R3 y R4" en sus identificadores. */
export function idList(cell: string): string[] {
  return cell
    .split(/[,;]|\s+y\s+/)
    .map((id) => id.trim())
    .filter((id) => id !== '');
}
queue-estimate.tsDescargar queue-estimate.ts
// Una cuenta para el análisis de un escenario de rendimiento con una cola:
// si llegan trabajos a un ritmo y un grupo de workers los atiende a otro,
// ¿cuánto se acumula y cuánto espera el último?
//
//   node queue-estimate.ts <llegadas por minuto> <minutos> <workers> <segundos por trabajo>
//   node queue-estimate.ts 20 30 2 12
//
// Es el tipo de análisis que pide un ATAM: rudimentario, hecho en la reunión
// y suficiente para decir si una decisión es un riesgo. Supone llegadas a
// ritmo constante y trabajos que tardan todos lo mismo, y que la cola empieza
// vacía. Con llegadas en ráfaga y tiempos variables la espera real es mayor,
// sobre todo cuando la utilización se acerca a 1: si esta cuenta ya dice que
// no alcanza, medir no hace falta; si dice que alcanza por poco, sí.

import { pathToFileURL } from 'node:url';

export type QueueInput = {
  /** Trabajos que llegan por minuto durante el pico. */
  arrivalsPerMinute: number;
  /** Cuánto dura el pico, en minutos. */
  minutes: number;
  /** Cuántos workers atienden, uno a la vez cada uno. */
  workers: number;
  /** Lo que tarda un worker en un trabajo, en segundos. */
  secondsPerJob: number;
};

export type QueueEstimate = {
  /** Trabajos por minuto que atienden todos los workers juntos. */
  capacityPerMinute: number;
  /** Llegadas entre capacidad. Por encima de 1, la cola crece mientras dure el pico. */
  utilization: number;
  /** Trabajos que quedan pendientes cuando termina el pico. */
  backlogAtEnd: number;
  /** Lo que espera en la cola el último trabajo del pico, en minutos. */
  waitOfLastMinutes: number;
  /** El menor número de workers con el que la cola no crece. */
  workersToKeepUp: number;
};

export function estimate(input: QueueInput): QueueEstimate {
  const { arrivalsPerMinute, minutes, workers, secondsPerJob } = input;
  for (const [name, value] of Object.entries(input)) {
    if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} debe ser un número mayor que cero`);
  }
  if (!Number.isInteger(workers)) throw new RangeError('workers debe ser un número entero');

  const capacityPerMinute = (workers * 60) / secondsPerJob;
  const backlogAtEnd = Math.max(0, (arrivalsPerMinute - capacityPerMinute) * minutes);
  return {
    capacityPerMinute,
    utilization: arrivalsPerMinute / capacityPerMinute,
    backlogAtEnd,
    // El último en llegar tiene por delante todo lo acumulado.
    waitOfLastMinutes: backlogAtEnd / capacityPerMinute,
    workersToKeepUp: Math.ceil((arrivalsPerMinute * secondsPerJob) / 60),
  };
}

function round(value: number): string {
  return String(Math.round(value * 100) / 100).replace('.', ',');
}

function main(args: string[]): number {
  const [arrivalsPerMinute, minutes, workers, secondsPerJob] = args.map(Number);
  if (args.length !== 4) {
    console.error('Uso: node queue-estimate.ts <llegadas por minuto> <minutos> <workers> <segundos por trabajo>');
    return 2;
  }
  let result: QueueEstimate;
  try {
    result = estimate({ arrivalsPerMinute: arrivalsPerMinute!, minutes: minutes!, workers: workers!, secondsPerJob: secondsPerJob! });
  } catch (error) {
    console.error((error as Error).message);
    return 2;
  }
  console.log(`llegan ${round(arrivalsPerMinute!)} por minuto durante ${round(minutes!)} min; ${workers} workers, ${round(secondsPerJob!)} s por trabajo`);
  console.log(`capacidad:            ${round(result.capacityPerMinute)} por minuto`);
  console.log(`utilización:          ${round(result.utilization)}`);
  console.log(`pendientes al final:  ${round(result.backlogAtEnd)}`);
  console.log(`espera del último:    ${round(result.waitOfLastMinutes)} min`);
  console.log(`workers para no acumular: ${result.workersToKeepUp}`);
  return 0;
}

if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
  process.exitCode = main(process.argv.slice(2));
}
example/yupana/docs/arc42.mdDescargar example/yupana/docs/arc42.md
# Arquitectura de Yupana

El documento de arquitectura de Yupana, con las doce secciones de arc42. Es un
esquema: cada sección tiene lo que alguien del equipo o de la facultad ya
vino a preguntar, y enlaza los archivos donde vive el detalle en vez de
copiarlos.

## 1. Introducción y objetivos

Yupana es el juez de tareas de programación de la facultad: recibe la solución
de un estudiante, la ejecuta contra casos de prueba ocultos y publica un
veredicto. Lo usan 6 cursos.

Objetivos de calidad, en orden:

1. El veredicto llega mientras el estudiante todavía trabaja en la tarea,
   también la noche del cierre (E1).
2. El programa de un estudiante no puede leer nada que no sea suyo ni afectar
   a los demás (E2).
3. Ningún envío confirmado se pierde (E3).

| Stakeholder | Qué espera |
|---|---|
| Estudiantes | Veredicto pronto y el mismo trato para todos |
| Docentes | Publicar una tarea sin ayuda, y confiar en los veredictos |
| Jefes de práctica (el equipo) | Poder operarlo dos personas a tiempo parcial |
| Administración de servidores de la facultad | Que no comprometa la máquina ni la red de la facultad |

## 2. Restricciones

- Corre en una máquina virtual de la facultad, con 4 núcleos. No hay
  presupuesto para servicios en la nube.
- El inicio de sesión es el de la universidad (OpenID Connect): Yupana no
  guarda contraseñas.
- La facultad respalda solo la base de datos, cada noche.
- Node.js y PostgreSQL, que es lo que el equipo conoce.

## 3. Contexto y alcance

El diagrama de contexto: [`c4/context.md`](c4/context.md). Yupana no decide
quién está matriculado (lo dice el sistema de matrícula) ni registra las
notas del curso: entrega veredictos, y cada docente decide qué hace con ellos.

## 4. Estrategia de solución

- Recibir y calificar son procesos distintos, unidos por una tabla de
  trabajos en PostgreSQL (ADR 0003): atiende E1 sin agregar infraestructura.
- Todo código de estudiantes corre dentro de un sandbox sin red y con
  límites, en los workers y nunca en la API: atiende E2.
- El envío y su código se guardan en una transacción antes de confirmar
  (ADR 0002): atiende E3.

## 5. Vista de bloques

- Nivel 1, los contenedores: [`c4/containers.md`](c4/containers.md).
- Nivel 2, los componentes de la API: [`c4/components.md`](c4/components.md).
- El worker de calificación todavía no tiene su diagrama de componentes: son
  tres archivos, y se leen más rápido que un diagrama.

## 6. Vista de ejecución

Un envío, desde que el estudiante lo manda hasta que ve el veredicto:

1. La aplicación web manda el archivo a la API (HTTPS).
2. *HTTP* le pregunta a *Sesiones* quién es, y le entrega el envío a *Envíos*.
3. *Envíos* comprueba con *Cursos*, *Tareas* y *Lenguajes* que la persona
   está matriculada, la tarea sigue abierta y el lenguaje está aceptado.
4. *Envíos* guarda el envío, su código y un trabajo pendiente en una
   transacción. La API responde 202 con el identificador del envío.
5. Un worker, en su consulta de cada 2 s, toma el trabajo y lo marca "en
   calificación".
6. El worker compila el código y lo ejecuta contra cada caso de prueba dentro
   de un sandbox, y anota el veredicto.
7. La aplicación web, que pregunta cada 3 s, recibe el veredicto de
   *Veredictos* y lo muestra.

Falta escribir el recorrido de un worker que muere en el paso 6: hoy no está
decidido (ver la sección 11).

## 7. Vista de despliegue

Una máquina virtual de la facultad, con 4 núcleos y Linux. En ella corren la
API (un proceso), 2 workers de calificación, PostgreSQL y el cron de la
sincronización de matrícula. La carpeta de casos de prueba está en el disco
de la misma máquina. Delante hay un proxy de la facultad que termina HTTPS.

## 8. Conceptos transversales

- Sesiones: después del inicio de sesión con la universidad, Yupana emite su
  propia cookie firmada, válida por 8 horas.
- Errores de la API: siempre `{ "error": { "code", "message" } }`.
- Estados de un envío: pendiente, en calificación, y un veredicto final
  (aceptado, respuesta incorrecta, tiempo excedido, error de compilación,
  error en ejecución). Solo los workers cambian el estado.
- Horas: en UTC en la base de datos; el cierre de una tarea se compara con el
  reloj de la base de datos, no con el del navegador.

## 9. Decisiones de arquitectura

| ADR | Decisión | Estado |
|---|---|---|
| [0001](adr/0001-calificar-dentro-del-pedido-http.md) | Calificar cada envío dentro del pedido HTTP | Reemplazado por el ADR 0003 |
| [0002](adr/0002-guardar-el-codigo-de-los-envios-en-postgresql.md) | Guardar el código de los envíos en PostgreSQL | Aceptado |
| [0003](adr/0003-tabla-de-trabajos-y-workers-de-calificacion.md) | Calificar fuera de la API, con una tabla de trabajos y workers | Aceptado |

## 10. Requisitos de calidad

El utility tree está en [`utility-tree.md`](utility-tree.md) y los escenarios
completos en [`scenarios.md`](scenarios.md).

## 11. Riesgos y deuda técnica

Los riesgos de la última evaluación están en [`atam.md`](atam.md). Los dos
temas: la tabla de trabajos no tiene reglas de cola (capacidad, trabajos
abandonados, prioridades), y los workers tienen más acceso del que necesitan.
Deuda conocida: no hay política para archivar los envíos de semestres pasados
(ADR 0002).

## 12. Glosario

| Término | Significado |
|---|---|
| Envío | Un archivo de código que un estudiante manda como solución de una tarea |
| Caso de prueba | Un archivo de entrada y su salida esperada |
| Veredicto | El resultado de calificar un envío: aceptado, respuesta incorrecta, tiempo excedido, error de compilación o error en ejecución |
| Cierre | El momento desde el cual una tarea ya no acepta envíos |
| Trabajo | La fila que dice que un envío está pendiente de calificar |
| Sandbox | El entorno aislado en el que se ejecuta el programa de un estudiante |
example/yupana/docs/atam.mdDescargar example/yupana/docs/atam.md
# ATAM reducido de Yupana

Ejemplo lleno de la tabla del laboratorio (`atam-template.md`). La
arquitectura que se evalúa es la de `c4/`, con las decisiones de `adr/`; los
escenarios E1 a E3 están completos en `scenarios.md`.

- Sistema: Yupana
- Presenta: los dos jefes de práctica que mantienen Yupana
- Evalúa: un docente de Algoritmos y la administradora de los servidores de la facultad

## Objetivos del negocio

- El estudiante recibe el veredicto mientras todavía está trabajando en la tarea, también la noche del cierre.
- Un veredicto dice la verdad: nadie obtiene "aceptado" sin resolver la tarea, y nadie ve el código de otra persona.
- Ningún envío confirmado se pierde.
- Dos jefes de práctica a tiempo parcial pueden operar el sistema.

## Enfoques de arquitectura

| Id | Enfoque | Dónde se ve |
|---|---|---|
| A1 | Calificación asíncrona: una tabla de trabajos en PostgreSQL que los workers consultan cada 2 s (ADR 0003) | Contenedores: API → Base de datos ← Worker de calificación |
| A2 | Un sandbox nuevo por envío, sin red, con el sistema de archivos de solo lectura y límites de CPU, memoria y número de procesos | Contenedores: Worker de calificación |
| A3 | El envío, su código y su trabajo pendiente se guardan en una sola transacción (ADR 0002) | Componentes: Envíos → Base de datos |
| A4 | Todo en una máquina virtual de 4 núcleos: la API, 2 workers y PostgreSQL | arc42, sección 7 |
| A5 | Un solo usuario de PostgreSQL para la API, los workers y la sincronización | Contenedores: las tres flechas hacia Base de datos |
| A6 | Los casos de prueba en una carpeta del servidor que el worker monta dentro del sandbox | Contenedores: Worker de calificación → Carpeta de casos de prueba |

## Escenarios

| Id | Escenario | Atributo | Origen |
|---|---|---|---|
| E1 | 600 envíos en los 30 min antes de un cierre (20 por minuto, 12 s de calificación cada uno): confirmación en 1 s o menos (p95) y veredicto en 2 min o menos (p95) | rendimiento | utility tree (A, A) |
| E2 | Un programa intenta leer fuera de su carpeta, abrir una conexión y crear procesos sin límite: 0 bytes leídos, 0 conexiones, veredicto en 30 s o menos, 0 envíos ajenos afectados | seguridad | utility tree (A, A) |
| E3 | Un worker muere a mitad de una calificación: veredicto en 5 min o menos, 0 envíos perdidos, 0 con dos veredictos | disponibilidad | utility tree (A, A) |
| E6 | Un docente corrige un caso de prueba cuando ya hay 250 envíos: todos se recalifican en 60 min o menos y los envíos nuevos mantienen su veredicto en 2 min o menos (p95) | rendimiento | lluvia de ideas (4 votos) |
| E7 | Dos tareas cierran a la misma hora: 40 envíos por minuto durante 30 min, con veredicto en 2 min o menos (p95) | rendimiento | lluvia de ideas (2 votos) |

## Hallazgos

| Id | Tipo | Escenarios | Enfoques | Decisión | Atributos | Razonamiento |
|---|---|---|---|---|---|---|
| R1 | riesgo | E1, E7 | A1, A4 | Correr 2 workers, porque la máquina virtual tiene 4 núcleos | rendimiento | Con 12 s por envío, 2 workers califican 10 por minuto y llegan 20: al cierre quedan 300 pendientes y el último espera 30 min, contra una medida de 2 min. Para no acumular hacen falta 4 workers, que ocuparían los 4 núcleos (`queue-estimate.ts`) |
| S1 | punto de sensibilidad | E1, E7 | A1 | El número de workers y el límite de tiempo de cada tarea | rendimiento | La espera del veredicto depende del producto de los dos: envíos por minuto por segundos por envío, entre 60, da los workers que hacen falta. Duplicar el límite de tiempo de una tarea duplica los workers necesarios; E7 duplica las llegadas y tiene el mismo efecto |
| N1 | no riesgo | E1 | A1, A3 | Confirmar el envío con una transacción que inserta dos filas | rendimiento | La confirmación no espera a la calificación: cuesta dos escrituras pequeñas. Supuesto: la base de datos responde en decenas de milisegundos, lo normal mientras la máquina no esté saturada (ver R1) |
| N2 | no riesgo | E2 | A2 | Ejecutar cada programa sin red y con límites de CPU, memoria y número de procesos | seguridad | El programa no puede abrir conexiones ni agotar la máquina: al crear procesos sin límite choca con el tope y termina con error en ejecución. Supuesto: el aislamiento del kernel no tiene una falla conocida, lo que obliga a mantener el sistema operativo actualizado |
| R2 | riesgo | E2 | A5 | Los workers se conectan a la base de datos con el mismo usuario que la API | seguridad | El worker ejecuta código que no es nuestro. Si un programa escapa del sandbox, encuentra credenciales que leen el código de todos los envíos y cambian cualquier veredicto: el daño de una falla del sandbox no está acotado |
| R3 | riesgo | E2 | A6 | Montar en el sandbox la carpeta completa del caso de prueba, con la entrada y la salida esperada | seguridad | El programa puede leer la salida esperada e imprimirla: obtiene "aceptado" sin resolver la tarea, y la medida de 0 bytes leídos fuera de la carpeta del envío no se cumple |
| R4 | riesgo | E3 | A1 | Falta decidir qué pasa con un trabajo que un worker tomó y no terminó | disponibilidad | El worker marca el trabajo "en calificación" al tomarlo. Si muere, nadie lo devuelve a "pendiente": el envío queda sin veredicto para siempre, y el escenario pide 5 min |
| N3 | no riesgo | E3 | A3 | Guardar el código del envío en la misma transacción que su registro | disponibilidad | Un envío confirmado está completo en la base de datos aunque el worker muera: siempre se puede volver a calificar. Supuesto: el respaldo nocturno de la base de datos sigue funcionando |
| T1 | punto de trade-off | E1, E2 | A2 | Crear un sandbox nuevo para cada envío en vez de reutilizar uno | seguridad, rendimiento | Nada de un envío queda para el siguiente (seguridad), y cada envío paga el tiempo de crear y destruir el sandbox (rendimiento), que entra en los segundos por envío de S1 |
| T2 | punto de trade-off | E2, E3 | A1 | Cuántas veces se vuelve a intentar un trabajo abandonado (todavía sin decidir) | disponibilidad, seguridad | Más intentos recuperan más caídas pasajeras (E3). Pero un envío que mata al worker a propósito (E2) se ejecuta otra vez en cada intento y tumba un worker cada vez |
| R5 | riesgo | E6 | A1 | Atender los trabajos en orden de llegada, sin prioridades | rendimiento | Una recalificación mete 250 trabajos de golpe: a 10 por minuto son 25 min en los que todo envío nuevo espera detrás de ellos, contra una medida de 2 min |

## Temas de riesgo

| Tema | Riesgos | Objetivo del negocio que amenaza |
|---|---|---|
| La tabla de trabajos se adoptó como almacenamiento y nadie decidió sus reglas de cola: capacidad, trabajos abandonados y prioridades | R1, R4, R5 | El estudiante recibe el veredicto mientras todavía está trabajando en la tarea |
| El límite de confianza rodea al worker, y debería rodear al programa del estudiante | R2, R3 | Un veredicto dice la verdad, y nadie ve el código de otra persona |
example/yupana/docs/scenarios.mdDescargar example/yupana/docs/scenarios.md
# Escenarios de calidad de Yupana

Los cinco escenarios del utility tree (`utility-tree.md`), con sus seis
partes. Formato: el template de la semana 2 (`code/week-02/scenario-template.md`).

## E1. El cierre de una tarea

- **Atributo de calidad:** rendimiento
- **Fuente del estímulo:** los 300 estudiantes de una tarea de Algoritmos
- **Estímulo:** 600 envíos en los 30 minutos anteriores al cierre (20 por minuto), que tardan en promedio 12 s en calificarse
- **Artefacto:** el camino de un envío: la API, la tabla de trabajos y los workers de calificación
- **Entorno:** el servidor de la facultad en operación normal, sin otra tarea que cierre a la misma hora
- **Respuesta:** la API confirma cada envío y su veredicto aparece en la página del estudiante
- **Medida de la respuesta:** confirmación en 1 s o menos (p95), veredicto en 2 min o menos desde la confirmación (p95) y 0 envíos perdidos, medidos con una prueba de carga que reproduce las llegadas

## E2. Un programa que intenta salir del sandbox

- **Atributo de calidad:** seguridad
- **Fuente del estímulo:** un estudiante matriculado, con su propia cuenta
- **Estímulo:** envía un programa que intenta leer archivos fuera de la carpeta de su envío (la salida esperada de los casos, el código de otros), abrir una conexión de red y crear procesos sin límite
- **Artefacto:** el worker de calificación y su sandbox
- **Entorno:** operación normal, con otros envíos en la cola
- **Respuesta:** el programa termina con el veredicto "error en ejecución" y los demás envíos se siguen calificando
- **Medida de la respuesta:** 0 bytes leídos fuera de la carpeta del envío, 0 conexiones salientes, veredicto en 30 s o menos y 0 envíos de otras personas afectados, comprobado con una suite de 20 programas hostiles

## E3. Un worker muere a mitad de una calificación

- **Atributo de calidad:** disponibilidad
- **Fuente del estímulo:** el sistema operativo del servidor
- **Estímulo:** mata un worker que se quedó sin memoria mientras calificaba un envío
- **Artefacto:** los workers de calificación y la tabla de trabajos
- **Entorno:** la última hora antes de un cierre, con trabajos pendientes en la cola
- **Respuesta:** el envío se vuelve a calificar y el estudiante ve un solo veredicto
- **Medida de la respuesta:** veredicto en 5 min o menos desde la caída, 0 envíos perdidos y 0 envíos con dos veredictos, comprobado matando un worker 10 veces durante una prueba de carga

## E4. Un lenguaje nuevo

- **Atributo de calidad:** modificabilidad
- **Fuente del estímulo:** un jefe de práctica que no escribió Yupana
- **Estímulo:** agrega Java a los lenguajes aceptados
- **Artefacto:** el código de la API y de los workers, y la imagen del sandbox
- **Entorno:** durante el semestre, con tareas abiertas
- **Respuesta:** los estudiantes pueden enviar archivos `.java` y reciben veredicto
- **Medida de la respuesta:** 3 días-persona o menos, cambios en 1 módulo (Lenguajes) y en la imagen del sandbox, 0 cambios en los handlers de la API y 5 min o menos sin calificar durante el despliegue

## E5. El proveedor de identidad no responde

- **Atributo de calidad:** disponibilidad
- **Fuente del estímulo:** el proveedor de identidad de la universidad
- **Estímulo:** deja de responder durante 15 minutos
- **Artefacto:** la API (Sesiones)
- **Entorno:** la última hora antes de un cierre
- **Respuesta:** quien ya inició sesión sigue enviando, y quien intenta iniciar sesión recibe un mensaje que dice qué pasa
- **Medida de la respuesta:** 100 % de los envíos de personas con sesión abierta confirmados, y el mensaje de error del inicio de sesión en 3 s o menos
example/yupana/docs/utility-tree.mdDescargar example/yupana/docs/utility-tree.md
# Utility tree de Yupana

Las hojas son los escenarios de `scenarios.md`. Cada una lleva dos notas,
Alta (A), Media (M) o Baja (B): valor para el negocio y dificultad o riesgo
técnico, como en la semana 2.

| Atributo | Refinamiento | Escenario (resumen) | Negocio | Técnica |
|---|---|---|---|---|
| Rendimiento | Espera del veredicto | E1. 600 envíos en los 30 min antes de un cierre: confirmación en 1 s o menos (p95) y veredicto en 2 min o menos (p95) | A | A |
| Seguridad | Aislamiento del código enviado | E2. Un programa intenta leer fuera de su carpeta, usar la red y crear procesos sin límite: 0 bytes leídos, 0 conexiones, 0 envíos ajenos afectados | A | A |
| Disponibilidad | Falla propia | E3. Un worker muere a mitad de una calificación: veredicto en 5 min o menos, 0 envíos perdidos, 0 con dos veredictos | A | A |
| Modificabilidad | Lenguajes | E4. Agregar Java: 3 días-persona o menos, 1 módulo y la imagen del sandbox | M | B |
| Disponibilidad | Falla de un sistema externo | E5. El proveedor de identidad no responde 15 min: quien tiene sesión sigue enviando; error de inicio de sesión en 3 s o menos | A | M |

- Utilidad
  - Rendimiento
    - Espera del veredicto
      - **E1 (A, A)**
  - Seguridad
    - Aislamiento del código enviado
      - **E2 (A, A)**
  - Disponibilidad
    - Falla propia
      - **E3 (A, A)**
    - Falla de un sistema externo
      - E5 (A, M)
  - Modificabilidad
    - Lenguajes
      - E4 (M, B)

Los tres (A, A) son los que recorre la evaluación de `atam.md`.
example/yupana/docs/adr/0001-calificar-dentro-del-pedido-http.mdDescargar example/yupana/docs/adr/0001-calificar-dentro-del-pedido-http.md
# ADR 0001: Calificar cada envío dentro del pedido HTTP

## Contexto

Yupana empieza como piloto en una sección de Programación 1, con 40
estudiantes. Lo construyen y lo mantienen dos jefes de práctica a tiempo
parcial, y corre en una máquina virtual de la facultad con 4 núcleos. Las
tareas del piloto son programas pequeños: compilar una solución y ejecutarla
contra sus casos de prueba tarda unos 2 s. Todavía no sabemos si otros cursos
lo van a adoptar ni qué tan pesadas serán sus tareas.

Hay que decidir dónde y cuándo se califica un envío: es la decisión que le da
forma al resto del sistema.

**Escenario:** en la última hora antes de un cierre, los 40 estudiantes de la
sección envían hasta 5 soluciones por minuto, de unos 2 s de calificación
cada una; el estudiante ve su veredicto en 10 s o menos en el 95 % de los
envíos.

## Alternativas consideradas

### A. Calificar dentro del pedido HTTP

- **Gana:** es lo más simple de construir y de operar: un solo proceso y
  ningún estado intermedio. El estudiante recibe el veredicto en la misma
  respuesta.
- **Cuesta:** el pedido dura lo que dure la calificación; el proceso que
  atiende a todos es también el que compila y ejecuta código de estudiantes;
  y la capacidad de calificar es la de esa máquina, compartida con todo lo
  demás.

### B. Tabla de trabajos en PostgreSQL y un worker aparte

- **Gana:** la API responde apenas guarda el envío; el código de los
  estudiantes sale del proceso de la API; se pueden agregar workers.
- **Cuesta:** un proceso más que desplegar y vigilar, un estado "pendiente"
  que hay que mostrar, y la aplicación web tiene que volver a preguntar por el
  veredicto.
- **Por qué no:** con 5 envíos por minuto de 2 s resuelve un problema que el
  piloto no tiene, y cada pieza adicional la operan dos personas a tiempo
  parcial.

### C. Broker de mensajes y workers

- **Gana:** lo mismo que B, y además el broker entrega cada trabajo a un
  worker sin que nadie pregunte.
- **Cuesta:** lo mismo que B, más un broker que instalar, vigilar y
  respaldar.
- **Por qué no:** las mismas razones que B, con un costo de operación mayor.

## Decisión

- **Alternativa elegida:** A

Vamos a compilar y ejecutar cada envío dentro del pedido HTTP que lo recibe,
con un límite de 10 s por envío. Con 5 envíos por minuto de unos 2 s, el
servidor pasa calificando 10 s de cada 60: el escenario se cumple con margen.

Vamos a revisar esta decisión si Yupana pasa a usarse en más de una sección,
si aparecen tareas que tarden más de 5 s en calificarse, o cuando termine el
piloto, lo que ocurra primero.

## Estado

Reemplazado por el ADR 0003

## Consecuencias

- **Buena:** el piloto arranca con un proceso y una base de datos, sin
  infraestructura nueva.
- **Buena:** no existe el estado "pendiente": un envío tiene veredicto o no
  existe, y la aplicación web no necesita volver a preguntar.
- **Mala:** los envíos se califican en la misma máquina y al mismo tiempo que
  se atienden los demás pedidos. Una tanda de envíos pesados vuelve lenta toda
  la aplicación, y no hay forma de limitar cuántos se califican a la vez sin
  hacer esperar a quien envía.
- **Mala:** el código de los estudiantes se ejecuta como proceso hijo del
  proceso que tiene las credenciales de la base de datos.
- **Neutra:** si el navegador corta la conexión antes de la respuesta, el
  estudiante tiene que buscar el veredicto en su lista de envíos.
example/yupana/docs/adr/0002-guardar-el-codigo-de-los-envios-en-postgresql.mdDescargar example/yupana/docs/adr/0002-guardar-el-codigo-de-los-envios-en-postgresql.md
# ADR 0002: Guardar el código de los envíos en PostgreSQL

## Contexto

Un envío es un archivo de código fuente de hasta 64 KB; la aplicación rechaza
los más grandes. Hay que conservarlo: el docente lo revisa, y un envío puede
volver a calificarse si se corrige un caso de prueba. Lo que no puede pasar
es que se pierda un envío que el estudiante vio como recibido, porque después
del cierre ya no puede enviarlo otra vez.

La facultad respalda la base de datos cada noche. No respalda ninguna otra
carpeta del servidor, y no tiene un servicio de almacenamiento de objetos.

**Escenario:** el servidor se reinicia sin aviso durante la última hora antes
de un cierre; se pierden 0 envíos confirmados al estudiante y quedan 0 envíos
registrados sin su código.

## Alternativas consideradas

### A. Una columna de texto en la tabla de envíos

- **Gana:** el registro del envío y su código se guardan en una sola
  transacción: después de un reinicio están los dos o no está ninguno. Entra
  en el respaldo que ya existe. No agrega ninguna pieza.
- **Cuesta:** la base de datos crece con cada envío. Con el tope de 64 KB y
  unos 50 000 envíos por semestre, son como máximo 3,2 GB por semestre. Las
  consultas que listan envíos tienen que cuidarse de no traer esa columna.

### B. Un archivo en el disco del servidor, con su ruta en la base de datos

- **Gana:** la base de datos se mantiene pequeña, y los archivos se pueden
  mirar con cualquier herramienta.
- **Cuesta:** son dos escrituras que no comparten transacción: un reinicio
  entre las dos deja una fila sin archivo o un archivo sin fila. La carpeta
  no está en el respaldo.
- **Por qué no:** no cumple el escenario sin construir un procedimiento que
  reconcilie filas y archivos, y sin conseguir un respaldo que hoy no existe.

### C. Almacenamiento de objetos

- **Gana:** crece sin un límite práctico y sirve bien archivos grandes.
- **Cuesta:** un servicio más que operar o que pagar, y la misma falta de
  transacción que B.
- **Por qué no:** los envíos son pequeños. Resuelve un problema de tamaño que
  no tenemos y trae el problema de consistencia que queremos evitar.

## Decisión

- **Alternativa elegida:** A

Vamos a guardar el código de cada envío en una columna de la tabla de envíos,
en la misma transacción que registra el envío. La API confirma al estudiante
solo después del `COMMIT`.

Los casos de prueba no entran en esta decisión: son archivos de hasta decenas
de megabytes que un docente sube pocas veces, y van en una carpeta del
servidor. Vamos a revisar la decisión si el tope de 64 KB deja de alcanzar,
por ejemplo si se aceptan proyectos de varios archivos.

## Estado

Aceptado

## Consecuencias

- **Buena:** un envío confirmado está completo y entra en el respaldo
  nocturno sin trabajo adicional.
- **Buena:** cualquier proceso que tenga acceso a la base de datos puede
  calificar un envío: no hace falta un disco compartido.
- **Mala:** la tabla de envíos crece sin parar. Hace falta una política para
  archivar los envíos de semestres pasados, y todavía no existe.
- **Mala:** el tope de 64 KB deja de ser un detalle de validación y pasa a
  ser una restricción de la arquitectura: subirlo cambia el tamaño de la base
  de datos y del respaldo.
- **Neutra:** la carpeta de casos de prueba queda fuera del respaldo
  nocturno; los docentes conservan sus propios archivos.
example/yupana/docs/adr/0003-tabla-de-trabajos-y-workers-de-calificacion.mdDescargar example/yupana/docs/adr/0003-tabla-de-trabajos-y-workers-de-calificacion.md
# ADR 0003: Calificar fuera de la API, con una tabla de trabajos y workers

## Contexto

Reemplaza al ADR 0001. Desde el piloto cambiaron tres cosas. Yupana se usa en
6 cursos, con tareas de hasta 300 estudiantes. Las tareas de Algoritmos
tienen casos de prueba grandes, y calificar un envío tarda en promedio 12 s.
Y en los cierres la aplicación entera se vuelve lenta, porque la API compite
por los 4 núcleos con los compiladores y con los programas de los
estudiantes: es la consecuencia mala que el ADR 0001 dejó anotada.

El equipo sigue siendo de dos personas a tiempo parcial, y el servidor sigue
siendo una máquina virtual de la facultad.

**Escenario:** en los 30 minutos antes de un cierre llegan 600 envíos (20 por
minuto) que tardan en promedio 12 s en calificarse; la API confirma cada
envío en 1 s o menos (p95), el veredicto aparece en 2 min o menos (p95) y no
se pierde ningún envío.

A ese ritmo llegan 240 s de trabajo de calificación por cada minuto de reloj:
cuatro procesadores ocupados todo el tiempo, sin contar la API ni la base de
datos.

## Alternativas consideradas

### A. Seguir calificando en la API, con un tope de calificaciones a la vez

- **Gana:** no cambia la estructura del sistema, y el tope protege a los
  demás pedidos.
- **Cuesta:** cuando el tope se alcanza, cada envío espera su turno con la
  conexión HTTP abierta: la confirmación tarda lo que tarde la cola.
- **Por qué no:** el escenario pide confirmar en 1 s, y aquí confirmar y
  calificar son la misma respuesta.

### B. Tabla de trabajos en PostgreSQL y workers que la consultan

- **Gana:** confirmar un envío es insertar su fila y su trabajo, en la
  transacción que ya decidió el ADR 0002. La calificación sale del proceso de
  la API. Se agregan workers sin tocar la API. No agrega infraestructura.
- **Cuesta:** cada worker pregunta cada 2 s si hay trabajo: hasta 2 s de
  demora por envío y consultas constantes a la base de datos. La aplicación
  web tiene que volver a preguntar por el veredicto. Y una tabla usada como
  cola necesita reglas que hay que escribir: quién toma cada trabajo, qué
  pasa con uno que quedó a medias, en qué orden se atienden.

### C. Un broker de mensajes (NATS JetStream) y workers suscritos

- **Gana:** el broker entrega cada trabajo a un worker sin consultas
  periódicas, y vuelve a entregar el que no fue confirmado.
- **Cuesta:** un servicio más que instalar, vigilar y respaldar. Y el envío
  (en PostgreSQL) y su mensaje (en el broker) ya no se escriben en una
  transacción: un reinicio entre los dos deja un envío confirmado que nadie
  va a calificar.
- **Por qué no:** frente a una medida de 2 min, los 2 s de la consulta
  periódica no importan; el servicio adicional y la escritura en dos lugares
  sí, para un equipo de dos personas.

## Decisión

- **Alternativa elegida:** B

Vamos a separar recibir de calificar. La API guarda el envío y un trabajo
pendiente en una transacción y responde. Los workers de calificación son
procesos aparte: cada uno toma un trabajo pendiente, lo marca como suyo en
una transacción para que ningún otro lo tome, lo califica dentro del sandbox
y anota el veredicto.

Cuántos workers corren es configuración del despliegue y no forma parte de
esta decisión. Vamos a revisarla si la medida del veredicto baja de 2 min a
pocos segundos, o si el equipo llega a operar un broker por otra razón.

## Estado

Aceptado

## Consecuencias

- **Buena:** confirmar un envío ya no depende de cuánto tarde calificarlo.
- **Buena:** el código de los estudiantes ya no se ejecuta como hijo del
  proceso de la API.
- **Mala:** aparecen los estados "pendiente" y "en calificación". La
  aplicación web tiene que mostrarlos y preguntar por el veredicto.
- **Mala:** la tabla de trabajos trae decisiones que antes no existían y que
  este ADR no toma: cuántos workers, qué se hace con un trabajo que un worker
  tomó y no terminó, y si todos los trabajos valen lo mismo.
- **Neutra:** los workers necesitan una conexión a la base de datos para
  tomar trabajos, leer el código y anotar veredictos.
example/yupana/docs/c4/components.mdDescargar example/yupana/docs/c4/components.md
# Yupana: diagrama de componentes de la API

- Nivel: componentes
- Sistema: Yupana
- Contenedor: API

El contenedor "API" del diagrama de contenedores, abierto: los módulos del
proceso que recibe los envíos. Alrededor quedan solo los contenedores, los
almacenes y los sistemas externos con los que algún componente habla
directamente. El worker de calificación no aparece: no habla con la API, sino
con la base de datos.

## Elementos

| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Aplicación web | contenedor | Las páginas de tareas, de envío y de veredictos; corre en el navegador de cada persona | TypeScript y HTML, sin framework |
| HTTP | componente | Router y handlers: convierte cada pedido en una llamada a un módulo, y cada resultado o error en una respuesta JSON | TypeScript sobre node:http |
| Sesiones | componente | Inicia sesión contra el proveedor de identidad y mantiene la sesión propia de Yupana, que dura 8 horas; dice quién hace cada pedido | Módulo de TypeScript; cookie firmada |
| Cursos | componente | Cursos, secciones y matriculados: responde si una persona es docente o estudiante de una sección | Módulo de TypeScript; SQL con pg |
| Tareas | componente | Las tareas con su enunciado, su cierre, sus límites de tiempo y memoria, y sus casos de prueba | Módulo de TypeScript; SQL con pg |
| Envíos | componente | Valida un envío (tamaño, lenguaje, tarea abierta), y guarda su código y su trabajo pendiente en una sola transacción | Módulo de TypeScript; SQL con pg |
| Veredictos | componente | Entrega el estado y el veredicto de un envío a quien lo hizo y a su docente | Módulo de TypeScript; SQL con pg |
| Lenguajes | componente | La tabla de lenguajes aceptados: extensión, cómo se compila y cómo se ejecuta cada uno. Los workers usan el mismo módulo | Módulo de TypeScript sin dependencias |
| Base de datos | almacén de datos | Cursos, secciones, matriculados, tareas, envíos con su código fuente, la tabla de trabajos pendientes y los veredictos | PostgreSQL 18 |
| Carpeta de casos de prueba | almacén de datos | Los archivos de entrada y de salida esperada de cada tarea, que los estudiantes no deben ver | Carpeta en el disco del servidor |
| Proveedor de identidad | sistema externo | Servicio de la universidad que comprueba la cuenta institucional de estudiantes y docentes | OpenID Connect sobre HTTPS |

## Relaciones

| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Aplicación web | HTTP | Pide tareas, manda envíos y pregunta por veredictos | HTTPS, JSON |
| HTTP | Sesiones | Pregunta quién hace el pedido | Llamada a función |
| HTTP | Tareas | Pide las tareas de una sección y publica las nuevas | Llamada a función |
| HTTP | Envíos | Entrega cada envío recibido | Llamada a función |
| HTTP | Veredictos | Pide el estado de un envío | Llamada a función |
| Sesiones | Proveedor de identidad | Canjea el código de inicio de sesión por la identidad de la persona | OpenID Connect sobre HTTPS |
| Sesiones | Cursos | Busca a la persona por su correo institucional | Llamada a función |
| Tareas | Cursos | Pregunta si la persona es docente de la sección | Llamada a función |
| Envíos | Cursos | Pregunta si la persona está matriculada en la sección de la tarea | Llamada a función |
| Envíos | Tareas | Pide el cierre y los límites de la tarea | Llamada a función |
| Envíos | Lenguajes | Pregunta si el lenguaje del archivo está aceptado | Llamada a función |
| Veredictos | Cursos | Pregunta si la persona puede ver el envío | Llamada a función |
| Cursos | Base de datos | Lee cursos, secciones y matriculados | Protocolo de PostgreSQL sobre TCP (SQL) |
| Tareas | Base de datos | Guarda las tareas y lee sus límites | Protocolo de PostgreSQL sobre TCP (SQL) |
| Tareas | Carpeta de casos de prueba | Escribe los archivos de cada caso de prueba | Sistema de archivos |
| Envíos | Base de datos | Guarda el envío, su código y su trabajo pendiente en una transacción | Protocolo de PostgreSQL sobre TCP (SQL) |
| Veredictos | Base de datos | Lee el estado y el veredicto de cada envío | Protocolo de PostgreSQL sobre TCP (SQL) |
example/yupana/docs/c4/containers.mdDescargar example/yupana/docs/c4/containers.md
# Yupana: diagrama de contenedores

- Nivel: contenedores
- Sistema: Yupana

La caja "Yupana" del diagrama de contexto, abierta: lo que tiene que estar
corriendo o existir para que un envío llegue a tener veredicto. El diagrama
no dice en qué máquinas corre cada cosa (eso está en la sección 7 de
`../arc42.md`). Las decisiones que le dieron esta forma están en `../adr/`.

## Elementos

| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Estudiante | persona | Envía sus soluciones a las tareas de programación y revisa el veredicto de cada envío | — |
| Docente | persona | Publica las tareas con sus casos de prueba y revisa los envíos de su sección | — |
| Aplicación web | contenedor | Las páginas de tareas, de envío y de veredictos; corre en el navegador de cada persona | TypeScript y HTML, sin framework |
| API | contenedor | Recibe cada envío, lo guarda y lo deja pendiente de calificar; entrega tareas y veredictos; mantiene las sesiones | Node.js 26, node:http |
| Worker de calificación | contenedor | Toma un envío pendiente, lo compila y lo ejecuta contra cada caso de prueba dentro de un sandbox, y anota el veredicto. Corren dos procesos iguales | Node.js 26; el sandbox usa los namespaces y cgroups de Linux |
| Sincronización de matrícula | contenedor | Programa que corre cada madrugada: trae la lista de matriculados de cada sección y actualiza quién puede enviar a qué tarea | Script de Node.js que lanza cron |
| Base de datos | almacén de datos | Cursos, secciones, matriculados, tareas, envíos con su código fuente, la tabla de trabajos pendientes y los veredictos | PostgreSQL 18 |
| Carpeta de casos de prueba | almacén de datos | Los archivos de entrada y de salida esperada de cada tarea, que los estudiantes no deben ver | Carpeta en el disco del servidor |
| Proveedor de identidad | sistema externo | Servicio de la universidad que comprueba la cuenta institucional de estudiantes y docentes | OpenID Connect sobre HTTPS |
| Sistema de matrícula | sistema externo | Sistema de la universidad que dice quién está matriculado en cada curso y sección | API REST de la oficina de registro |

## Relaciones

| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Estudiante | Aplicación web | Envía soluciones y consulta sus veredictos | Navegador web |
| Docente | Aplicación web | Publica tareas y casos de prueba, y revisa los envíos | Navegador web |
| Estudiante | Proveedor de identidad | Ingresa su cuenta institucional | Navegador web |
| Docente | Proveedor de identidad | Ingresa su cuenta institucional | Navegador web |
| Aplicación web | API | Pide tareas, manda envíos y pregunta cada 3 s por el veredicto de un envío pendiente | HTTPS, JSON |
| API | Proveedor de identidad | Canjea el código de inicio de sesión por la identidad de la persona | OpenID Connect sobre HTTPS |
| API | Base de datos | Guarda envíos y trabajos pendientes; lee tareas, matriculados y veredictos | Protocolo de PostgreSQL sobre TCP (SQL) |
| API | Carpeta de casos de prueba | Escribe los casos de prueba que sube un docente | Sistema de archivos |
| Worker de calificación | Base de datos | Pregunta cada 2 s por el siguiente trabajo pendiente, lo toma y anota el veredicto | Protocolo de PostgreSQL sobre TCP (SQL) |
| Worker de calificación | Carpeta de casos de prueba | Lee la entrada y la salida esperada de cada caso | Sistema de archivos, solo lectura |
| Sincronización de matrícula | Sistema de matrícula | Pide la lista de matriculados de cada sección | HTTPS, JSON |
| Sincronización de matrícula | Base de datos | Actualiza los matriculados de cada sección | Protocolo de PostgreSQL sobre TCP (SQL) |
example/yupana/docs/c4/context.mdDescargar example/yupana/docs/c4/context.md
# Yupana: diagrama de contexto

- Nivel: contexto
- Sistema: Yupana

Yupana es el juez de tareas de programación de una facultad: recibe la
solución de un estudiante, la compila, la ejecuta contra casos de prueba que
el estudiante no ve y le devuelve un veredicto. Este diagrama muestra quién
lo usa y de qué sistemas de la universidad depende.

## Elementos

| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|
| Estudiante | persona | Envía sus soluciones a las tareas de programación y revisa el veredicto de cada envío | — |
| Docente | persona | Publica las tareas con sus casos de prueba y revisa los envíos de su sección | — |
| Yupana | sistema | Recibe soluciones a tareas de programación, las ejecuta contra casos de prueba y publica el veredicto | Aplicación web con una API en Node.js, workers de calificación y PostgreSQL |
| Proveedor de identidad | sistema externo | Servicio de la universidad que comprueba la cuenta institucional de estudiantes y docentes | OpenID Connect sobre HTTPS |
| Sistema de matrícula | sistema externo | Sistema de la universidad que dice quién está matriculado en cada curso y sección | API REST de la oficina de registro |

## Relaciones

| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|
| Estudiante | Yupana | Envía soluciones y consulta sus veredictos | HTTPS, desde el navegador |
| Docente | Yupana | Publica tareas y casos de prueba, y revisa los envíos | HTTPS, desde el navegador |
| Estudiante | Proveedor de identidad | Ingresa su cuenta institucional | HTTPS, desde el navegador |
| Docente | Proveedor de identidad | Ingresa su cuenta institucional | HTTPS, desde el navegador |
| Yupana | Proveedor de identidad | Canjea el código de inicio de sesión por la identidad de la persona | OpenID Connect sobre HTTPS |
| Yupana | Sistema de matrícula | Pide la lista de matriculados de cada sección | HTTPS, JSON |

Errores

Ejemplos con errores a propósito: no compilan, fallan o dan un resultado incorrecto. Los apuntes explican cada uno.

errors/atam.mdDescargar errors/atam.md
# ATAM reducido de Yupana

Una tabla con los errores más frecuentes. `make errors` muestra lo que el
revisor dice de cada uno.

- Sistema: Yupana
- Presenta: los dos jefes de práctica que mantienen Yupana
- Evalúa: un docente de Algoritmos

## Objetivos del negocio

- El estudiante recibe el veredicto mientras todavía está trabajando en la tarea.

## Enfoques de arquitectura

| Id | Enfoque | Dónde se ve |
|---|---|---|
| A1 | Calificación asíncrona: una tabla de trabajos en PostgreSQL que los workers consultan cada 2 s | Contenedores: API → Base de datos ← Worker de calificación |
| A2 | Sandbox | Workers |

## Escenarios

| Id | Escenario | Atributo | Origen |
|---|---|---|---|
| E1 | 600 envíos en los 30 min antes de un cierre: veredicto en 2 min o menos (p95) | rendimiento | utility tree (A, A) |
| E2 | El sistema debe ser seguro frente a programas maliciosos | seguridad | utility tree (A, A) |
| E3 | Un worker muere a mitad de una calificación: veredicto en 5 min o menos | disponibilidad | utility tree (A, A) |

## Hallazgos

| Id | Tipo | Escenarios | Enfoques | Decisión | Atributos | Razonamiento |
|---|---|---|---|---|---|---|
| R1 | riesgo | E1 | A1 | Podría ser lento | rendimiento | Hay muchos envíos |
| R2 | problema | E1 | A1 | Correr 2 workers en una máquina de 4 núcleos | rendimiento | Con 12 s por envío, 2 workers califican 10 por minuto y llegan 20 |
| T1 | punto de trade-off | E2 | A2 | Crear un sandbox nuevo para cada envío en vez de reutilizar uno | seguridad | Nada de un envío queda para el siguiente, y cada envío paga el tiempo de crear el sandbox |
| S1 | riesgo | E1 | A1 | El número de workers y el límite de tiempo de cada tarea | rendimiento | La espera del veredicto depende del producto de los dos valores |
| R3 | riesgo | E9 | A7 | Los workers usan el mismo usuario de PostgreSQL que la API | seguridad | Si un programa escapa del sandbox, encuentra credenciales que leen todos los envíos |

## Temas de riesgo

| Tema | Riesgos | Objetivo del negocio que amenaza |
|---|---|---|
| Falta capacidad de calificación en los cierres | R1 | El estudiante recibe el veredicto mientras todavía está trabajando |
errors/adr/0004-usar-un-broker.mdDescargar errors/adr/0004-usar-un-broker.md
# ADR 0004: Usar un broker

## Contexto

La calificación es lenta y los estudiantes se quejan.

## Alternativas consideradas

### A. NATS

- **Gana:** es rápido y moderno.

## Decisión

Decidimos usar NATS.

## Estado

Decidido

## Consecuencias

- **Buena:** la calificación va a ser más rápida.
errors/adr/0005-preguntar-por-el-veredicto-cada-tres-segundos.mdDescargar errors/adr/0005-preguntar-por-el-veredicto-cada-tres-segundos.md
# ADR 0005: Preguntar por el veredicto cada 3 s desde la aplicación web

## Contexto

Desde el ADR 0003 un envío no recibe su veredicto en la respuesta: queda
pendiente, y la aplicación web tiene que enterarse de cuándo termina.

**Escenario:** con 300 estudiantes esperando un veredicto a la vez, cada uno
lo ve en su página 5 s o menos después de que el worker lo anota (p95).

## Alternativas consideradas

### A. La aplicación web pregunta cada 3 s

- **Gana:** es un `GET` más, sin nada nuevo en el servidor ni en el proxy de
  la facultad.
- **Cuesta:** 300 estudiantes esperando son 100 pedidos por segundo que casi
  siempre responden "todavía no".

### B. Server-sent events

- **Gana:** el servidor avisa una vez, cuando hay veredicto.
- **Cuesta:** una conexión abierta por estudiante que espera, y hay que
  comprobar que el proxy de la facultad no las corte.
- **Por qué no:** no sabemos cómo se comporta el proxy con conexiones largas.

### C. WebSocket

- **Gana:** lo mismo que B, y además permite mensajes en los dos sentidos.
- **Cuesta:** lo mismo que B, más un protocolo que la API hoy no habla.
- **Por qué no:** no necesitamos mensajes del navegador al servidor.

## Decisión

- **Alternativa elegida:** A

Vamos a preguntar cada 3 s mientras un envío esté pendiente: cumple la medida
de 5 s y no depende del proxy. Vamos a revisarlo si esos pedidos llegan a
pesar en la API durante un cierre.

## Estado

Reemplazado por el ADR 0006

## Consecuencias

- **Buena:** no hay conexiones largas que cuidar.
- **Mala:** la carga de la API crece con la cantidad de gente que espera, no
  con la cantidad de veredictos.
errors/adr/0006-avisar-el-veredicto-con-server-sent-events.mdDescargar errors/adr/0006-avisar-el-veredicto-con-server-sent-events.md
# ADR 0006: Avisar el veredicto con server-sent events

## Contexto

En el último cierre, los pedidos que preguntan por un veredicto fueron la
mayor parte del tráfico de la API. La administración de servidores confirmó
que el proxy de la facultad mantiene conexiones abiertas hasta 10 minutos.

**Escenario:** con 300 estudiantes esperando un veredicto a la vez, cada uno
lo ve en su página 5 s o menos después de que el worker lo anota (p95), y la
API recibe menos de 10 pedidos por segundo por ese motivo.

## Alternativas consideradas

### A. Seguir preguntando, cada 10 s

- **Gana:** no cambia nada más.
- **Cuesta:** el veredicto puede tardar 10 s en verse.
- **Por qué no:** no cumple la medida de 5 s.

### B. Server-sent events

- **Gana:** un aviso por veredicto, en vez de un pedido cada 3 s por persona.
- **Cuesta:** 300 conexiones abiertas en la API durante un cierre, y la
  aplicación web tiene que reconectarse si el proxy corta una.

### C. WebSocket

- **Gana:** lo mismo que B.
- **Cuesta:** lo mismo que B, más un protocolo que la API hoy no habla.
- **Por qué no:** no necesitamos mensajes del navegador al servidor.

## Decisión

- **Alternativa elegida:** B

Vamos a abrir una conexión de server-sent events por cada envío pendiente y
a cerrarla cuando llegue el veredicto.

## Estado

Propuesto

## Consecuencias

- **Buena:** la carga de la API deja de depender de cuánta gente espera.
- **Mala:** la API tiene que enterarse de que un worker anotó un veredicto, y
  hoy los workers no le avisan a nadie.

Pruebas

Comprueban lo que afirman los apuntes; se ejecutan con make test.

adr.test.tsDescargar adr.test.ts
// Pruebas del formato de ADR del curso (adr-template.md) y de su revisor.
// Comprueban lo que dicen los apuntes de la semana 7: qué tiene que llevar un
// ADR, qué estados existen y cómo se reemplaza una decisión sin reescribirla.

import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { describe, test } from 'node:test';
import { MIN_ALTERNATIVES, SECTIONS, checkAdr, checkSet, type NamedAdr } from './adr.ts';

const here = import.meta.dirname;
const read = (path: string): string => readFileSync(`${here}/${path}`, 'utf8');

type Parts = {
  number?: string;
  context?: string;
  scenario?: string;
  alternatives?: string[];
  decision?: string;
  status?: string;
  consequences?: string[];
};

const ALTERNATIVE_A = ['### A. Una cola en memoria', '', '- **Gana:** no agrega ninguna pieza nueva', '- **Cuesta:** los trabajos se pierden si el proceso se reinicia'];
const ALTERNATIVE_B = [
  '### B. Una tabla de trabajos',
  '',
  '- **Gana:** los trabajos sobreviven a un reinicio',
  '- **Cuesta:** los workers consultan la tabla cada 2 s',
  '- **Por qué no:** el equipo no quiere consultas periódicas',
];
const ALTERNATIVE_C = [
  '### C. Un broker de mensajes',
  '',
  '- **Gana:** entrega cada trabajo sin consultas periódicas',
  '- **Cuesta:** un servicio más que instalar y vigilar',
  '- **Por qué no:** dos personas no pueden operar otro servicio',
];

/** Un ADR correcto, con las partes que se le cambien. */
function adr(parts: Parts = {}): string {
  return [
    `# ADR ${parts.number ?? '0007'}: Guardar los trabajos en memoria`,
    '',
    '## Contexto',
    '',
    parts.context ?? 'El piloto tiene una sola sección y un solo servidor.',
    '',
    parts.scenario ?? '**Escenario:** llegan 5 envíos por minuto y cada veredicto aparece en 10 s o menos (p95).',
    '',
    '## Alternativas consideradas',
    '',
    ...(parts.alternatives ?? [...ALTERNATIVE_A, '', ...ALTERNATIVE_B, '', ...ALTERNATIVE_C]),
    '',
    '## Decisión',
    '',
    parts.decision ?? '- **Alternativa elegida:** A\n\nVamos a guardar los trabajos en memoria: con 5 envíos por minuto, perder la cola en un reinicio afecta a muy pocos envíos.',
    '',
    '## Estado',
    '',
    parts.status ?? 'Aceptado',
    '',
    '## Consecuencias',
    '',
    ...(parts.consequences ?? ['- **Buena:** no hay nada nuevo que operar', '- **Mala:** un reinicio pierde los trabajos pendientes']),
    '',
  ].join('\n');
}

const rules = (text: string): string[] => checkAdr(text).issues.map((issue) => issue.rule);
const named = (file: string, text: string): NamedAdr => ({ file, adr: checkAdr(text).adr });

describe('las partes de un ADR', () => {
  test('las secciones son las de Nygard más las alternativas consideradas, en este orden', () => {
    assert.deepEqual([...SECTIONS], ['Contexto', 'Alternativas consideradas', 'Decisión', 'Estado', 'Consecuencias']);
  });

  test('un ADR completo no tiene errores', () => {
    const { adr: read, issues } = checkAdr(adr());
    assert.deepEqual(issues, []);
    assert.equal(read.number, '0007');
    assert.equal(read.chosen, 'A');
    assert.equal(read.status, 'aceptado');
    assert.equal(read.alternatives.length, 3);
  });

  test('sin una de las cinco secciones, no pasa', () => {
    for (const section of SECTIONS) {
      const text = adr().replace(new RegExp(`## ${section}\\n[\\s\\S]*?(?=\\n## |$)`), '');
      assert.ok(rules(text).includes('secciones'), `debería faltar "${section}"`);
    }
  });

  test('una sección vacía no cuenta como sección', () => {
    assert.ok(rules(adr({ consequences: [] })).includes('vacia'));
  });

  test('el título lleva el número de cuatro dígitos', () => {
    assert.ok(rules(adr().replace('# ADR 0007:', '# ADR 7:')).includes('titulo'));
    assert.ok(rules(adr().replace('# ADR 0007: ', '# ')).includes('titulo'));
  });

  test('el template sin llenar no pasa: queda su texto entre ángulos', () => {
    const found = rules(read('adr-template.md'));
    assert.ok(found.includes('template'));
    assert.ok(found.includes('titulo'));
  });
});

describe('el contexto nombra el escenario', () => {
  test('sin el párrafo **Escenario:** no pasa', () => {
    assert.ok(rules(adr({ scenario: 'La calificación es lenta y los estudiantes se quejan.' })).includes('escenario'));
  });

  test('un escenario sin ningún número no tiene medida', () => {
    assert.ok(rules(adr({ scenario: '**Escenario:** llegan muchos envíos y el veredicto debe aparecer pronto.' })).includes('escenario'));
  });

  test('el escenario puede ocupar varias líneas', () => {
    const scenario = '**Escenario:** llegan 5 envíos por minuto\ny cada veredicto aparece en 10 s o menos (p95).';
    const { adr: read, issues } = checkAdr(adr({ scenario }));
    assert.deepEqual(issues, []);
    assert.match(read.scenario, /5 envíos por minuto y cada veredicto/);
  });
});

describe('las alternativas', () => {
  test('hacen falta la elegida y al menos dos más', () => {
    assert.equal(MIN_ALTERNATIVES, 3);
    assert.ok(rules(adr({ alternatives: [...ALTERNATIVE_A, '', ...ALTERNATIVE_B] })).includes('alternativas'));
    assert.ok(rules(adr({ alternatives: ALTERNATIVE_A })).includes('alternativas'));
    assert.deepEqual(rules(adr({ alternatives: [...ALTERNATIVE_A, '', ...ALTERNATIVE_B, '', ...ALTERNATIVE_C] })), []);
  });

  test('toda alternativa dice qué gana y qué cuesta, también la elegida', () => {
    const withoutCost = ALTERNATIVE_A.filter((line) => !line.includes('**Cuesta:**'));
    const { issues } = checkAdr(adr({ alternatives: [...withoutCost, '', ...ALTERNATIVE_B, '', ...ALTERNATIVE_C] }));
    assert.equal(issues.length, 1);
    assert.match(issues[0]!.message, /alternativa A no dice qué cuesta/);
  });

  test('una alternativa descartada dice por qué no; la elegida no lo necesita', () => {
    const withoutWhy = ALTERNATIVE_C.filter((line) => !line.includes('**Por qué no:**'));
    const { issues } = checkAdr(adr({ alternatives: [...ALTERNATIVE_A, '', ...ALTERNATIVE_B, '', ...withoutWhy] }));
    assert.equal(issues.length, 1);
    assert.match(issues[0]!.message, /alternativa C se descartó y no dice por qué/);
  });

  test('la decisión nombra una de las alternativas consideradas', () => {
    const reasoning = 'Vamos a hacerlo así porque el escenario pide confirmar cada envío en 1 s o menos.';
    assert.ok(rules(adr({ decision: reasoning })).includes('decision'));
    assert.ok(rules(adr({ decision: `- **Alternativa elegida:** D\n\n${reasoning}` })).includes('decision'));
    assert.ok(rules(adr({ decision: '- **Alternativa elegida:** A' })).includes('decision'), 'elegir sin explicar no alcanza');
  });

  test('el valor de un ítem puede seguir en la línea de abajo, con sangría', () => {
    const wrapped = ['### A. Una cola en memoria', '', '- **Gana:** no agrega', '  ninguna pieza nueva', '- **Cuesta:** los trabajos se pierden', '  si el proceso se reinicia'];
    const { adr: read, issues } = checkAdr(adr({ alternatives: [...wrapped, '', ...ALTERNATIVE_B, '', ...ALTERNATIVE_C] }));
    assert.deepEqual(issues, []);
    assert.equal(read.alternatives[0]!.gains, 'no agrega ninguna pieza nueva');
  });
});

describe('el estado', () => {
  test('los estados permitidos', () => {
    for (const status of ['Propuesto', 'Aceptado', 'Rechazado', 'Obsoleto', 'Reemplazado por el ADR 0009', 'Aceptado.']) {
      assert.deepEqual(rules(adr({ status })), [], status);
    }
  });

  test('cualquier otro texto no es un estado', () => {
    for (const status of ['Decidido', 'Aceptado en la reunión del lunes', 'Reemplazado', 'Reemplazado por el ADR 9', 'En discusión']) {
      assert.deepEqual(rules(adr({ status })), ['estado'], status);
    }
  });

  test('un ADR no se reemplaza a sí mismo', () => {
    assert.deepEqual(rules(adr({ status: 'Reemplazado por el ADR 0007' })), ['reemplazo']);
  });
});

describe('las consecuencias', () => {
  test('hace falta al menos una buena y una mala', () => {
    assert.deepEqual(rules(adr({ consequences: ['- **Buena:** todo va a ser más rápido'] })), ['consecuencias']);
    assert.deepEqual(rules(adr({ consequences: ['- **Mala:** hay un servicio más que operar'] })), ['consecuencias']);
  });

  test('las neutras se cuentan aparte', () => {
    const { adr: read } = checkAdr(adr({ consequences: ['- **Buena:** uno', '- **Mala:** dos', '- **Neutra:** tres', '- **Mala:** cuatro'] }));
    assert.deepEqual(read.consequences, { good: 1, bad: 2, neutral: 1 });
  });
});

describe('reemplazar una decisión sin reescribirla', () => {
  const OLD = 'docs/adr/0007-en-memoria.md';
  const NEW = 'docs/adr/0009-tabla.md';
  const oldAdr = (status: string): NamedAdr => named(OLD, adr({ status }));
  const newAdr = (status: string, context = 'Reemplaza al ADR 0007. Ahora hay seis cursos.'): NamedAdr => named(NEW, adr({ number: '0009', status, context }));

  test('el par correcto: el viejo apunta al nuevo, y el nuevo dice a quién reemplaza', () => {
    assert.deepEqual(checkSet([oldAdr('Reemplazado por el ADR 0009'), newAdr('Aceptado')]), []);
  });

  test('un ADR reemplazado apunta a uno que existe', () => {
    const issues = checkSet([oldAdr('Reemplazado por el ADR 0009')]);
    assert.equal(issues.length, 1);
    assert.equal(issues[0]!.rule, 'reemplazo');
    assert.match(issues[0]!.message, /ADR 0009, que no está entre los archivos revisados/);
  });

  test('quien reemplaza se escribió después', () => {
    const early = named('docs/adr/0003-antes.md', adr({ number: '0003', context: 'Reemplaza al ADR 0007.' }));
    const issues = checkSet([early, oldAdr('Reemplazado por el ADR 0003')]);
    assert.ok(issues.some((issue) => /es anterior/.test(issue.message)));
  });

  test('mientras el nuevo esté solo propuesto, el viejo sigue vigente', () => {
    const issues = checkSet([oldAdr('Reemplazado por el ADR 0009'), newAdr('Propuesto')]);
    assert.equal(issues.length, 1);
    assert.equal(issues[0]!.file, OLD);
    assert.match(issues[0]!.message, /todavía no fue aceptado/);
  });

  test('el nuevo dice en su contexto a quién reemplaza', () => {
    const issues = checkSet([oldAdr('Reemplazado por el ADR 0009'), newAdr('Aceptado', 'Ahora hay seis cursos.')]);
    assert.equal(issues.length, 1);
    assert.equal(issues[0]!.file, NEW);
  });

  test('si el nuevo fue aceptado, en el viejo cambia el estado (y solo el estado)', () => {
    const issues = checkSet([oldAdr('Aceptado'), newAdr('Aceptado')]);
    assert.equal(issues.length, 1);
    assert.equal(issues[0]!.file, OLD);
    assert.match(issues[0]!.message, /Reemplazado por el ADR 0009/);
  });

  test('una cadena de reemplazos también vale', () => {
    const last = named('docs/adr/0012-broker.md', adr({ number: '0012', context: 'Reemplaza al ADR 0009.' }));
    assert.deepEqual(checkSet([oldAdr('Reemplazado por el ADR 0009'), newAdr('Reemplazado por el ADR 0012'), last]), []);
  });
});

describe('la numeración', () => {
  test('el número del archivo es el del título', () => {
    const issues = checkSet([named('docs/adr/0008-en-memoria.md', adr())]);
    assert.equal(issues.length, 1);
    assert.equal(issues[0]!.rule, 'numeracion');
  });

  test('los números no se repiten', () => {
    const issues = checkSet([named('a/0007-uno.md', adr()), named('b/0007-otro.md', adr())]);
    assert.equal(issues.length, 1);
    assert.match(issues[0]!.message, /no se repiten/);
  });
});

describe('check-adr.ts', () => {
  const run = (...args: string[]) => spawnSync(process.execPath, ['check-adr.ts', ...args], { cwd: here, encoding: 'utf8' });

  test('los tres ADR de Yupana pasan, con uno reemplazado', () => {
    const result = run('example/yupana/docs/adr');
    assert.equal(result.status, 0, result.stdout);
    assert.match(result.stdout, /ADR 0001, Reemplazado por el ADR 0003, 3 alternativas \(elegida: A\): sin errores/);
    assert.match(result.stdout, /ADR 0003, Aceptado, 3 alternativas \(elegida: B\): sin errores/);
  });

  test('el ADR 0001 de Yupana, revisado solo, no puede comprobar su reemplazo', () => {
    const result = run('example/yupana/docs/adr/0001-calificar-dentro-del-pedido-http.md');
    assert.equal(result.status, 1);
    assert.match(result.stdout, /\[reemplazo\]/);
  });

  test('los ADR de errors/ fallan por lo que dicen los apuntes', () => {
    const result = run('errors/adr');
    assert.equal(result.status, 1);
    for (const rule of ['escenario', 'alternativas', 'decision', 'estado', 'consecuencias', 'reemplazo']) {
      assert.match(result.stdout, new RegExp(`\\[${rule}\\]`), rule);
    }
    assert.match(result.stdout, /0004-usar-un-broker\.md: ADR 0004, estado desconocido, 1 alternativa \(sin elegida\): 6 errores/);
  });

  test('sin argumentos termina con código 2', () => {
    assert.equal(run().status, 2);
  });
});
atam.test.tsDescargar atam.test.ts
// Pruebas de la tabla del ATAM reducido (atam-template.md) y de su revisor.
// Comprueban las definiciones de los apuntes: qué es un riesgo, un no riesgo,
// un punto de sensibilidad, un punto de trade-off y un tema de riesgo.

import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { describe, test } from 'node:test';
import { FINDING_KINDS, checkEvaluation, countByKind } from './atam.ts';

const here = import.meta.dirname;
const read = (path: string): string => readFileSync(`${here}/${path}`, 'utf8');

const RISK = '| R1 | riesgo | E1 | A1 | Correr 2 workers en una máquina de 4 núcleos | rendimiento | Con 12 s por envío, 2 workers califican 10 por minuto y llegan 20 |';
const NON_RISK = '| N1 | no riesgo | E2 | A1 | Confirmar el envío con una sola transacción | rendimiento | La confirmación cuesta dos escrituras pequeñas mientras la base de datos no esté saturada |';

/** Una tabla correcta, con las filas de hallazgos y de temas que se le pasen. */
function evaluation(findings: string[] = [RISK, NON_RISK], themes: string[] = [], scenarios?: string[]): string {
  return [
    '# ATAM reducido de Prueba',
    '',
    '- Sistema: Prueba',
    '',
    '## Objetivos del negocio',
    '',
    '- El veredicto llega mientras el estudiante todavía trabaja en la tarea.',
    '',
    '## Enfoques de arquitectura',
    '',
    '| Id | Enfoque | Dónde se ve |',
    '|---|---|---|',
    '| A1 | Calificación asíncrona con una tabla de trabajos | Contenedores: API → Base de datos |',
    '| A2 | Un sandbox nuevo por envío | Contenedores: Worker de calificación |',
    '',
    '## Escenarios',
    '',
    '| Id | Escenario | Atributo | Origen |',
    '|---|---|---|---|',
    ...(scenarios ?? [
      '| E1 | 600 envíos en 30 min: veredicto en 2 min o menos (p95) | rendimiento | utility tree (A, A) |',
      '| E2 | Un docente recalifica 250 envíos en 60 min o menos | rendimiento | lluvia de ideas (4 votos) |',
    ]),
    '',
    '## Hallazgos',
    '',
    '| Id | Tipo | Escenarios | Enfoques | Decisión | Atributos | Razonamiento |',
    '|---|---|---|---|---|---|---|',
    ...findings,
    '',
    '## Temas de riesgo',
    '',
    '| Tema | Riesgos | Objetivo del negocio que amenaza |',
    '|---|---|---|',
    ...themes,
    '',
  ].join('\n');
}

const rules = (text: string): string[] => checkEvaluation(text).issues.map((issue) => issue.rule);

describe('la tabla', () => {
  test('una tabla completa no tiene errores', () => {
    const result = checkEvaluation(evaluation());
    assert.deepEqual(result.issues, []);
    assert.equal(result.evaluation.system, 'Prueba');
    assert.deepEqual(countByKind(result.evaluation), { riesgo: 1, 'no riesgo': 1, 'punto de sensibilidad': 0, 'punto de trade-off': 0 });
  });

  test('los cuatro tipos de hallazgo y la letra de su identificador', () => {
    assert.deepEqual(FINDING_KINDS, { riesgo: 'R', 'no riesgo': 'N', 'punto de sensibilidad': 'S', 'punto de trade-off': 'T' });
  });

  test('el template sin llenar no pasa', () => {
    assert.ok(rules(read('atam-template.md')).includes('template'));
  });

  test('sin objetivos del negocio no hay contra qué comparar los riesgos', () => {
    assert.ok(rules(evaluation().replace('- El veredicto llega mientras el estudiante todavía trabaja en la tarea.', '')).includes('objetivos'));
  });

  test('un tipo que no existe se rechaza', () => {
    assert.ok(rules(evaluation([RISK.replace('| riesgo |', '| problema |'), NON_RISK])).includes('tipo'));
  });

  test('el identificador empieza con la letra de su tipo y no se repite', () => {
    assert.ok(rules(evaluation([RISK.replace('| R1 |', '| S1 |'), NON_RISK])).includes('id'));
    assert.ok(rules(evaluation([RISK, RISK, NON_RISK])).includes('id'));
  });
});

describe('los escenarios', () => {
  test('un escenario sin número no se puede recorrer: no hay medida contra la que comparar', () => {
    const vague = ['| E1 | El sistema debe ser rápido en los cierres | rendimiento | utility tree (A, A) |', '| E2 | Recalificar 250 envíos en 60 min o menos | rendimiento | lluvia de ideas (4 votos) |'];
    assert.deepEqual(rules(evaluation(undefined, [], vague)), ['escenario']);
  });

  test('hay escenarios del utility tree y de la lluvia de ideas', () => {
    const onlyTree = ['| E1 | 600 envíos en 30 min: veredicto en 2 min o menos | rendimiento | utility tree (A, A) |', '| E2 | Recalificar 250 envíos en 60 min o menos | rendimiento | utility tree (A, M) |'];
    assert.deepEqual(rules(evaluation(undefined, [], onlyTree)), ['origen']);
  });

  test('todo escenario recorrido deja al menos un hallazgo', () => {
    const { issues } = checkEvaluation(evaluation([RISK]));
    assert.equal(issues.length, 1);
    assert.equal(issues[0]!.rule, 'sin-analizar');
    assert.match(issues[0]!.message, /^E2 /);
  });
});

describe('los hallazgos', () => {
  test('un hallazgo nombra una decisión, no un síntoma', () => {
    const symptom = '| R1 | riesgo | E1 | A1 | Podría ser lento | rendimiento | Con 12 s por envío, 2 workers califican 10 por minuto y llegan 20 |';
    assert.deepEqual(rules(evaluation([symptom, NON_RISK])), ['decision']);
  });

  test('un hallazgo sin razonamiento es una opinión', () => {
    const noReason = '| R1 | riesgo | E1 | A1 | Correr 2 workers en una máquina de 4 núcleos | rendimiento | Hay muchos envíos |';
    assert.deepEqual(rules(evaluation([noReason, NON_RISK])), ['razonamiento']);
  });

  test('un hallazgo sale de recorrer un escenario sobre un enfoque: los dos existen en la tabla', () => {
    assert.deepEqual(rules(evaluation([RISK.replace('| E1 | A1 |', '| E9 | A1 |'), NON_RISK, NON_RISK.replace('N1', 'N2').replace('E2', 'E1')])), ['escenario']);
    assert.deepEqual(rules(evaluation([RISK.replace('| E1 | A1 |', '| E1 | A7 |'), NON_RISK])), ['enfoque']);
  });

  test('un punto de sensibilidad afecta a un atributo; un punto de trade-off, a dos o más', () => {
    const sensitivity = '| S1 | punto de sensibilidad | E1 | A1 | El número de workers y el límite de tiempo de cada tarea | rendimiento | La espera del veredicto depende del producto de los dos valores |';
    const tradeoff = '| T1 | punto de trade-off | E1 | A2 | Crear un sandbox nuevo para cada envío | seguridad, rendimiento | Nada de un envío queda para el siguiente, y cada envío paga crear el sandbox |';
    assert.deepEqual(rules(evaluation([RISK, NON_RISK, sensitivity, tradeoff])), []);

    const oneAttribute = tradeoff.replace('seguridad, rendimiento', 'seguridad');
    const { issues } = checkEvaluation(evaluation([RISK, NON_RISK, oneAttribute]));
    assert.equal(issues.length, 1);
    assert.match(issues[0]!.message, /con uno es un punto de sensibilidad/);

    // El mismo atributo dos veces sigue siendo uno.
    assert.deepEqual(rules(evaluation([RISK, NON_RISK, tradeoff.replace('seguridad, rendimiento', 'seguridad, Seguridad')])), ['atributos']);
  });
});

describe('los temas de riesgo', () => {
  const SECOND_RISK = '| R2 | riesgo | E2 | A1 | Atender los trabajos en orden de llegada, sin prioridades | rendimiento | Una recalificación mete 250 trabajos y todo envío nuevo espera detrás de ellos |';

  test('un tema agrupa por lo menos dos riesgos y dice qué objetivo amenaza', () => {
    const theme = '| Nadie decidió las reglas de la cola | R1, R2 | El veredicto llega mientras el estudiante trabaja |';
    assert.deepEqual(rules(evaluation([RISK, NON_RISK, SECOND_RISK], [theme])), []);
    assert.deepEqual(rules(evaluation([RISK, NON_RISK, SECOND_RISK], [theme.replace('R1, R2', 'R1')])), ['tema']);
    assert.deepEqual(rules(evaluation([RISK, NON_RISK, SECOND_RISK], [theme.replace('El veredicto llega mientras el estudiante trabaja', '—')])), ['tema']);
  });

  test('un tema agrupa riesgos: un no riesgo no entra', () => {
    const theme = '| Nadie decidió las reglas de la cola | R1, N1 | El veredicto llega mientras el estudiante trabaja |';
    assert.deepEqual(rules(evaluation([RISK, NON_RISK], [theme])), ['tema', 'tema']);
  });

  test('una tabla sin temas es válida: no todos los riesgos comparten causa', () => {
    assert.deepEqual(rules(evaluation([RISK, NON_RISK, SECOND_RISK], [])), []);
  });
});

describe('check-atam.ts', () => {
  const run = (...args: string[]) => spawnSync(process.execPath, ['check-atam.ts', ...args], { cwd: here, encoding: 'utf8' });

  test('la tabla de Yupana pasa', () => {
    const result = run('example/yupana/docs/atam.md');
    assert.equal(result.status, 0, result.stdout);
    assert.match(result.stdout, /6 enfoques, 5 escenarios, 5 riesgos, 3 no riesgos, 1 punto de sensibilidad, 2 puntos de trade-off, 2 temas de riesgo: sin errores/);
  });

  test('la tabla de errors/ falla por lo que dicen los apuntes', () => {
    const result = run('errors/atam.md');
    assert.equal(result.status, 1);
    for (const rule of ['enfoque', 'origen', 'escenario', 'sin-analizar', 'decision', 'razonamiento', 'tipo', 'atributos', 'id', 'tema']) {
      assert.match(result.stdout, new RegExp(`\\[${rule}\\]`), rule);
    }
  });

  test('sin argumentos termina con código 2', () => {
    assert.equal(run().status, 2);
  });
});
example.test.tsDescargar example.test.ts
// El ejemplo completo de la semana (Yupana) cumple todos los formatos del
// curso, y los documentos que se citan entre sí dicen lo mismo.

import assert from 'node:assert/strict';
import { readFileSync, readdirSync } from 'node:fs';
import { describe, test } from 'node:test';
import { checkDiagram, checkSet, normalize } from '../week-01/c4.ts';
import { checkMarkdown } from '../week-02/scenario-check.ts';
import { checkAdr, statusText } from './adr.ts';
import { ARC42_SECTIONS, checkOutline } from './arc42.ts';
import { checkEvaluation } from './atam.ts';

const docs = `${import.meta.dirname}/example/yupana/docs`;
const read = (path: string): string => readFileSync(`${docs}/${path}`, 'utf8');

describe('los diagramas C4 de Yupana', () => {
  const files = ['c4/context.md', 'c4/containers.md', 'c4/components.md'];
  const diagrams = files.map((file) => ({ file, ...checkDiagram(read(file)) }));

  test('los tres niveles pasan el revisor de la semana 1', () => {
    for (const { file, issues } of diagrams) assert.deepEqual(issues, [], file);
    assert.deepEqual(diagrams.map(({ diagram }) => diagram.level), ['contexto', 'contenedores', 'componentes']);
    assert.deepEqual(checkSet(diagrams), []);
  });

  test('el diagrama de componentes abre un contenedor que existe en el de contenedores', () => {
    const [, containers, components] = diagrams;
    const opened = containers!.diagram.elements.find((element) => normalize(element.name) === normalize(components!.diagram.container));
    assert.equal(opened?.kind, 'contenedor');
  });

  test('lo que rodea a los componentes ya estaba en el diagrama de contenedores, con el mismo nombre', () => {
    const [, containers, components] = diagrams;
    const known = new Set(containers!.diagram.elements.map((element) => normalize(element.name)));
    for (const element of components!.diagram.elements) {
      if (element.kind !== 'componente') assert.ok(known.has(normalize(element.name)), element.name);
    }
  });
});

describe('los demás documentos de Yupana', () => {
  test('los escenarios tienen sus seis partes y su medida (revisor de la semana 2)', () => {
    const report = checkMarkdown(read('scenarios.md'));
    assert.equal(report.ok, true);
    assert.equal(report.scenarios.length, 5);
  });

  test('las doce secciones de arc42, en orden', () => {
    assert.equal(ARC42_SECTIONS.length, 12);
    assert.deepEqual(checkOutline(read('arc42.md')), []);
  });

  test('la sección 9 de arc42 lista cada ADR con el estado que el ADR dice', () => {
    const outline = read('arc42.md');
    const files = readdirSync(`${docs}/adr`).sort();
    assert.equal(files.length, 3);
    for (const file of files) {
      const { adr } = checkAdr(read(`adr/${file}`));
      const row = outline.split('\n').find((line) => line.includes(`(adr/${file})`));
      assert.ok(row, `falta ${file} en la sección 9`);
      assert.ok(row.includes(adr.title), `${file}: el título no coincide`);
      assert.ok(row.trimEnd().endsWith(`| ${statusText(adr)} |`), `${file}: el estado no coincide`);
    }
  });

  test('los escenarios de la tabla de ATAM que vienen del utility tree son sus (A, A)', () => {
    const { evaluation } = checkEvaluation(read('atam.md'));
    const fromTree = evaluation.scenarios.filter((scenario) => scenario.origin.startsWith('utility tree')).map((scenario) => scenario.id);
    const top = read('utility-tree.md')
      .split('\n')
      .filter((line) => /\|\s*A\s*\|\s*A\s*\|\s*$/.test(line))
      .map((line) => /(E\d+)\./.exec(line)?.[1]);
    assert.deepEqual(fromTree, top);
    assert.deepEqual(fromTree, ['E1', 'E2', 'E3']);
  });
});

describe('arc42', () => {
  test('los nombres de las doce secciones', () => {
    assert.deepEqual(
      ARC42_SECTIONS.map((section) => section.english),
      [
        'Introduction and Goals',
        'Constraints',
        'Context and Scope',
        'Solution Strategy',
        'Building Block View',
        'Runtime View',
        'Deployment View',
        'Crosscutting Concepts',
        'Architecture Decisions',
        'Quality Requirements',
        'Risks and Technical Debt',
        'Glossary',
      ],
    );
  });

  test('sin una sección, o con dos en otro orden, no pasa', () => {
    const outline = read('arc42.md');
    const missing = outline.replace(/## 7\. Vista de despliegue\n[\s\S]*?(?=\n## 8\.)/, '');
    assert.ok(checkOutline(missing).some((issue) => /falta la sección "## 7\. Vista de despliegue"/.test(issue.message)));

    const glossary = /## 12\. Glosario\n[\s\S]*$/.exec(outline)![0];
    const moved = outline.replace(glossary, '').replace('## 2. Restricciones', `${glossary}\n## 2. Restricciones`);
    assert.ok(checkOutline(moved).some((issue) => /fuera de orden/.test(issue.message)));
  });

  test('una sección vacía no cuenta: si no se llena, se dice por qué', () => {
    const empty = read('arc42.md').replace(/(## 12\. Glosario\n)[\s\S]*$/, '$1');
    assert.deepEqual(checkOutline(empty).map((issue) => issue.rule), ['vacia']);
  });

  test('el template tiene las doce secciones y todavía su texto entre ángulos', () => {
    const issues = checkOutline(readFileSync(`${import.meta.dirname}/arc42-template.md`, 'utf8'));
    assert.equal(issues.length, 12);
    assert.ok(issues.every((issue) => issue.rule === 'template'));
  });
});
queue-estimate.test.tsDescargar queue-estimate.test.ts
// Pruebas de la cuenta de la cola. Los números son los que usan los apuntes
// y la tabla de ATAM de Yupana.

import assert from 'node:assert/strict';
import { test } from 'node:test';
import { estimate } from './queue-estimate.ts';

test('E1 con 2 workers: llegan 20 por minuto, salen 10, quedan 300 y el último espera 30 min', () => {
  const result = estimate({ arrivalsPerMinute: 20, minutes: 30, workers: 2, secondsPerJob: 12 });
  assert.equal(result.capacityPerMinute, 10);
  assert.equal(result.utilization, 2);
  assert.equal(result.backlogAtEnd, 300);
  assert.equal(result.waitOfLastMinutes, 30);
  assert.equal(result.workersToKeepUp, 4);
});

test('con 4 workers la cola no crece, pero no sobra nada: utilización 1', () => {
  const result = estimate({ arrivalsPerMinute: 20, minutes: 30, workers: 4, secondsPerJob: 12 });
  assert.equal(result.utilization, 1);
  assert.equal(result.backlogAtEnd, 0);
});

test('E7, dos tareas cierran a la vez: el doble de llegadas pide el doble de workers', () => {
  const result = estimate({ arrivalsPerMinute: 40, minutes: 30, workers: 2, secondsPerJob: 12 });
  assert.equal(result.workersToKeepUp, 8);
  assert.equal(result.backlogAtEnd, 900);
  assert.equal(result.waitOfLastMinutes, 90);
});

test('punto de sensibilidad: duplicar los segundos por envío duplica los workers necesarios', () => {
  const base = estimate({ arrivalsPerMinute: 20, minutes: 30, workers: 2, secondsPerJob: 12 });
  const slower = estimate({ arrivalsPerMinute: 20, minutes: 30, workers: 2, secondsPerJob: 24 });
  assert.equal(slower.workersToKeepUp, 2 * base.workersToKeepUp);
});

test('el piloto del ADR 0001: 5 envíos por minuto de 2 s ocupan un sexto de un proceso', () => {
  const result = estimate({ arrivalsPerMinute: 5, minutes: 60, workers: 1, secondsPerJob: 2 });
  assert.ok(Math.abs(result.utilization - 1 / 6) < 1e-12);
  assert.equal(result.backlogAtEnd, 0);
  assert.equal(result.workersToKeepUp, 1);
});

test('E6: recalificar 250 envíos a 10 por minuto toma 25 min', () => {
  const { capacityPerMinute } = estimate({ arrivalsPerMinute: 1, minutes: 1, workers: 2, secondsPerJob: 12 });
  assert.equal(250 / capacityPerMinute, 25);
});

test('rechaza entradas que no tienen sentido', () => {
  assert.throws(() => estimate({ arrivalsPerMinute: 0, minutes: 30, workers: 2, secondsPerJob: 12 }), RangeError);
  assert.throws(() => estimate({ arrivalsPerMinute: 20, minutes: 30, workers: 2.5, secondsPerJob: 12 }), RangeError);
});

Laboratorio

Archivos de partida del laboratorio de la semana.

lab/components.mdDescargar lab/components.md
# Tinkuy: diagrama de componentes del proceso principal

- Nivel: componentes
- Sistema: Tinkuy
- Contenedor: <el nombre que le pusieron al proceso principal en containers.md>

<!-- Dos o tres líneas: qué contenedor abre este diagrama y qué deja fuera. -->

## Elementos

<!-- Una fila por caja. Los componentes son las partes del proceso principal
     de SU Tinkuy, como quedó después de las semanas 3 a 6: un componente
     tiene una responsabilidad y una interfaz, y casi siempre coincide con una
     carpeta de src/. Alrededor van solo los contenedores, almacenes de datos,
     sistemas externos y personas con los que algún componente habla
     directamente, con los mismos nombres de containers.md. El contenedor que
     se abre ya no es una caja. -->

| Nombre | Tipo | Descripción | Tecnología |
|---|---|---|---|

## Relaciones

<!-- Una fila por flecha, en la dirección de quien llama. Entre componentes
     del mismo proceso el protocolo es "Llamada a función"; hacia afuera, el
     protocolo de verdad. Si `make deps` pasa en su Tinkuy, las flechas entre
     componentes de este diagrama son las que sus reglas permiten: compárenlas. -->

| De | Hacia | Qué viaja | Protocolo |
|---|---|---|---|

Compilación

Cómo se compilan y ejecutan los ejemplos.

MakefileDescargar Makefile
# Semana 7: decidir, documentar y evaluar una arquitectura. Se usa dentro del
# contenedor del curso. Esta semana no usa la base de datos ni la red: todo
# son documentos y los programas que los revisan.
#
#   make              lo mismo que make example
#   make test         revisa los tipos (tsc) y corre las pruebas (*.test.ts):
#                     los revisores de ADR, de la tabla de ATAM y de arc42, la
#                     cuenta de la cola y el ejemplo completo (Yupana)
#   make example      revisa el ejemplo: sus tres diagramas C4 (con el revisor
#                     de la semana 1), sus escenarios (con el de la semana 2),
#                     sus ADR, su documento arc42 y su tabla de ATAM
#   make errors       revisa los documentos con errores de errors/: falla a propósito
#   make check-c4     revisa sus diagramas:  make check-c4 DOCS=/work/tinkuy-suusuario/docs
#   make check-adr    revisa sus ADR:        make check-adr DOCS=/work/tinkuy-suusuario/docs
#   make check-atam   revisa su tabla:       make check-atam DOCS=/work/tinkuy-suusuario/docs
#   make queue        la cuenta de una cola: make queue ARRIVALS=20 MINUTES=30 WORKERS=2 SECONDS=12
#   make clean        no hay nada que borrar: la semana no genera archivos
#
# Los templates para el laboratorio: adr-template.md, atam-template.md,
# arc42-template.md y lab/components.md. El formato de los diagramas y su
# revisor son los de ../week-01 (c4-format.md, check-c4.ts).

WEEK01 ?= ../week-01
WEEK02 ?= ../week-02
EXAMPLE := example/yupana/docs
DOCS ?= docs
ARRIVALS ?= 20
MINUTES ?= 30
WORKERS ?= 2
SECONDS ?= 12

.PHONY: all test example errors check-c4 check-adr check-atam queue clean

all: example

test:
	tsc -p .
	node --test "*.test.ts"

example:
	node $(WEEK01)/check-c4.ts $(EXAMPLE)/c4/context.md $(EXAMPLE)/c4/containers.md $(EXAMPLE)/c4/components.md
	node $(WEEK02)/scenario-check.ts $(EXAMPLE)/scenarios.md
	node check-adr.ts $(EXAMPLE)/adr
	node arc42.ts $(EXAMPLE)/arc42.md
	node check-atam.ts $(EXAMPLE)/atam.md

# Los revisores terminan con error cuando encuentran algo: aquí eso es lo que se quiere ver.
errors:
	@node check-adr.ts errors/adr ; echo "check-adr terminó con código $$?"
	@node check-atam.ts errors/atam.md ; echo "check-atam terminó con código $$?"

check-c4:
	node $(WEEK01)/check-c4.ts $(DOCS)/c4/context.md $(DOCS)/c4/containers.md $(DOCS)/c4/components.md

check-adr:
	node check-adr.ts $(DOCS)/adr

check-atam:
	node check-atam.ts $(DOCS)/atam.md

queue:
	@node queue-estimate.ts $(ARRIVALS) $(MINUTES) $(WORKERS) $(SECONDS)

clean:
	@true
package.jsonDescargar package.json
{
  "name": "week-07",
  "private": true,
  "type": "module"
}
tsconfig.jsonDescargar tsconfig.json
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["*.ts"],
  "exclude": ["build"]
}