npm package: @imolko/ultra-reporter
Description: Reporter and documentation for: domain, use-cases and tests
Author: Roberto Matute
Latest version: 2.1.13

## ¿Cómo usar ultra-reporter version 2?

1. Instale el paquete `@imolko/ultra-reporter` en su ultima version:

```bash
npm install @imolko/ultra-reporter
```

2. Instale el paquete `better-docs` en su repositorio:

Este paquete es una peer-dependency de `@imolko/ultra-reporter` y es necesario para generar la documentacion de los artefactos.

```bash
npm install better-docs --save-dev --legacy-peer-deps
```

3. Instale el paquete `jest-ctrf-json-reporter` en su ultima version:

```bash
npm i jest-ctrf-json-reporter --save-dev
```

4. Agregue la siguiente configuracion al jest en su archivo `jest.config.js`:

```js

module.exports = {
  ...
  reporters: [
    "default",
    [
      'jest-ctrf-json-reporter',
      {
        outputDir: '.',
        outputFile: 'ctrf.json',
      }
    ],
  ],
  ...
};
```

Ejecute los test para generar el archivo `ctrf.json`:

```bash
npm run test
```

5. Corra el comando para crear el proyecto de documentacion

Desde el root del repositorio, ejecute el siguiente comando:

```bash
npx @imolko/ultra-reporter init -d -p documentation
```

- _-d_ indica que debe mostrar todos los mensajes de debug.
- _-p_ indica el nombre del proyecto de documentacion (el nombre de la carpeta donde se generara la documentacion).

6. Configure el archivo `documentation/ultra-reporter.config.json`

```json
{
  "targets": [
    {
      "type": "domain", // Indica el tipo de target (domain/use-cases)
      "packageRoot": "./domain", // Indica el root del paquete tarjet
      "domainSrc": "./domain/src", // Indica el path de la carpeta dond estan todos los artefactos
      "contextName": "sentinel", // Indica el nombre del contexto (valor domain en el @RegisterValueObject del artefacto)
      "testsResultFile": "./domain/ctrf.json", // Indica el path del archivo de resultados de los test
      "docusaurus": {
        // Configuracion docusaurus para el tab domain y aggregates
        "domain": {
          "name": "sentinel-domain", // Indica el nombre del tab en docusaurus con contendra la documentacion de los artefactos: Entities y ValueObjects
          "config": {
            // Configuracion docusaurus para el tab
            "label": "Sentinel Domain Artifacts",
            "position": 2,
            "link": {
              "type": "generated-index",
              "description": "Todos los artefactos del dominio"
            }
          }
        },
        "aggregates": {
          "name": "sentinel-aggregates", // Indica el nombre del tab en docusaurus con contendra la documentacion de los artefactos: Agregates
          "config": {
            // Configuracion docusaurus para el tab (ver documentacion https://docusaurus.io/docs/sidebar/items#sidebar-item-category)
            "label": "Sentinel Aggregates",
            "position": 1,
            "link": {
              "type": "generated-index",
              "description": "Aggregates del dominio"
            }
          }
        }
      }
    },
    {
      "type": "use-cases", // Indica el tipo de target (domain/use-cases)
      "title": "Sentinel Use Cases", // Indica el titulo del tab en docusaurus con contendra la documentacion de los casos de uso
      "packageRoot": "./features", // Indica el root del paquete tarjet
      "useCasesSrc": "./features/src", // Indica el path de la carpeta dond estan todos los casos de uso
      "testsResultFile": "./features/ctrf.json", // Indica el path del archivo de resultados de los test
      "docusaurus": {
        // Configuracion docusaurus para el tab
        "useCases": {
          // Configuracion docusaurus para el tab (ver documentacion https://docusaurus.io/docs/sidebar/items#sidebar-item-category)
          "name": "sentinel-use-cases",
          "config": {
            "label": "Sentinel Use Cases",
            "position": 3,
            "link": {
              "type": "generated-index",
              "description": "Todos los casos de uso"
            }
          }
        }
      }
    }
  ]
}
```

7. Corra los test de jest

Corra los test de jest para generar el archivo `ctrf.json` en cad uno de los paquetes target

```bash
npm run test
```

ó

```bash
npx jest
```

8. Corra el comando para generar la documentacion:

Desde el root del repositorio, ejecute el siguiente comando:

```bash
npx @imolko/ultra-reporter generate-documentation -d -p documentation
```

- _-d_ indica que debe mostrar todos los mensajes de debug.
- _-p_ indica el nombre del proyecto de documentacion (el nombre de la carpeta donde se generara la documentacion).

## ¿Cómo correr el servidor web de documentación?

1. Estando dentro de la carpeta `documentation` instale las dependencias:

```bash
npm install
```

2. Corra el servidor de documentacion:

```bash
npm run start
```

## Consideraciones

1. La documentacion relacionada al paquete debe estar en un archivo llamado `context-intro.md` en la carpeta `src`.

2. Este generador asume que la estructura de los archivos en la capeta carpetta de cada artefacto hace uso del paquete `@imolko/ultra-ddd` y por tanto tiene una estructura como la siguiente:

```plaintext
domain
├── src
│   ├── Artifact1
│   │   ├── attachments.md
│   │   ├── conditions.ts
│   │   ├── definition.ts
│   │   ├── definition.yaml
│   │   ├── entity.spec.ts
│   │   ├── entity.ts
│   │   ├── index.ts
│   │   ├── payload.ts
│   │   ├── primitive.ts
│   │   ├── props.ts
│   └── Artifact2
│   │   ├── ...
└── context-intro.md
```

Los archivos `attachments.md` y `definition.yaml` contiene parte importante de la documentacion de los artefactos, por lo que es importante que esten presentes en la estructura de los archivos y este bien documentados.

3. En la carpeta `documentation` se generan los archivos relacionados con la documentacion de los artefactos y una introducccion al contexto.

4. Dentro de `documentation` hay archivos que deben ser editados para ajustarlos a cada contexto, como:

- `/documentation/docusaurus.config.ts`

5. Dentro de `documentation` se pueden generar paginas y blogs para documentar de forma manual otros aspectos del contexto. Vea [Docusaurus](https://docusaurus.io/docs/)