Quick Start

# One-time setup (interactive wizard)
npm create @imolko/ultra-reporter

# Daily workflow
npm run docs:serve     # Generate docs + start dev server at http://localhost:3000
npm run docs:gen       # Generate docs only (CI/CD)
npm run docs:build     # Production static build

The wizard auto-detects your project structure and asks a few questions with smart defaults. After setup, everything lives in:

| Location | Purpose | Git | |---|---|---| | ultra-reporter.config.json | Your configuration | ✅ Commit | | docs/ | Your manual markdown files | ✅ Commit | | .ultra-reporter/ | Generated docs + Docusaurus internals | ❌ Gitignored | | .ultra-reporter-overrides/ | Optional theme customizations | ✅ Commit |

Command Reference

ultra-reporter create

Interactive wizard to configure ultra-reporter. Can also be run non-interactively:

ultra-reporter create \
  --domain-name sentinel \
  --domain-src ./domain/src \
  --use-cases-src ./features/src \
  --docs-path ./docs \
  --repo-source-url https://github.com/myorg/myrepo

ultra-reporter serve [--port 3000] [--full]

Generates documentation, assembles the Docusaurus site, installs dependencies (first run), and starts the dev server. Watches source files for changes.

• --port: Port to serve on (default: 3000)
• --full: Force full regeneration including JSDoc extraction (slower)

ultra-reporter generate

Generates documentation without starting a server. Useful for CI/CD pipelines.

ultra-reporter build [--output ./public]

Generates documentation and produces a static production build. Output goes to .ultra-reporter/build/ by default, configurable via --output.

Configuration

ultra-reporter.config.json at your project root:

{
  "repoSourceUrl": "https://github.com/myorg/myrepo",
  "domain": {
    "name": "sentinel",
    "srcPath": "./domain/src",
    "testResultsPath": "./domain/ctrf.json"
  },
  "useCases": {
    "title": "Sentinel Use Cases",
    "srcPath": "./features/src",
    "testResultsPath": "./features/ctrf.json"
  },
  "docs": {
    "path": "./docs"
  }
}

Only domain.name and domain.srcPath are required. All other fields are optional.

Test Integration

If you use Jest, the wizard can install and configure jest-ctrf-json-reporter automatically. This adds a reporters entry to your jest config:

reporters: [
  "default",
  ["jest-ctrf-json-reporter", { outputDir: ".", outputFile: "ctrf.json" }]
]

Run your tests before generating docs:

npm run test

Manual Docs

Place .md files in your configured docs/ folder. They'll appear in the documentation site under the "Documentation" section.

Customization

For advanced customization, create a .ultra-reporter-overrides/ folder:

.ultra-reporter-overrides/
├── docusaurus.config.override.ts   # Merged with generated config
├── custom.css                       # Additional CSS
├── components/                      # Custom React components
└── static/                          # Extra static assets (logos, favicon)

Old Workflow (deprecated)

The previous workflow using init and generate-documentation commands is still available but deprecated. New projects should use the create → serve/generate/build workflow.

Consideraciones

1. El generador escanea todos los archivos .md dentro de cada carpeta de artefacto y extrae el frontmatter de cada uno. El metadata se mergea combinando todos los .md, y sus cuerpos se concatenan en orden alfabético para formar la documentación del artefacto. Se recomienda usar README.md como nombre para el archivo de explicación, siguiendo el mismo patrón que GitHub y GitLab usan en sus exploradores online.

2. El archivo definition.yaml ya no es requerido. Si existe, se carga como metadata base, y el frontmatter de los .md lo sobrescribe. Para proyectos nuevos, toda la metadata puede declararse directamente como frontmatter en los archivos .md.

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

domain
├── src
│   ├── Artifact1
│   │   ├── README.md
│   │   ├── conditions.ts
│   │   ├── definition.ts
│   │   ├── entity.spec.ts
│   │   ├── entity.ts
│   │   ├── index.ts
│   │   ├── payload.ts
│   │   ├── primitive.ts
│   │   ├── props.ts
│   └── Artifact2
│   │   ├── ...
└── README.md

Los archivos .md contienen la documentación de los artefactos a través de su frontmatter y cuerpo. Es importante que estén presentes y bien documentados.

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

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

• /documentation/docusaurus.config.ts

6. Dentro de documentation se pueden generar paginas y blogs para documentar de forma manual otros aspectos del contexto. Vea Docusaurus

🛠 Desarrollo del generador (para contributors)

Si vas a modificar las plantillas o scripts que generan la documentación, usa este flujo para iterar rápidamente.

Arquitectura

El generador tiene dos capas que producen la documentación final:

| Capa | Qué controla | Dónde editar | |---|---|---| | 1. Contenido .md | Layout de páginas de artefactos y use-cases, estructura de cards, estilos inline de los docs generados | src/reporters/rendering.ts (templates), src/reporters/generate-*.ts (orquestadores), src/reporters/data-*.ts (carga y transformación) | | 2. Sitio Docusaurus | CSS, branding, navbar, footer, landing page, sidebar | templates/documentation/ |

Detalle de archivos — Capa 1

| Archivo | Función | |---|---| | src/reporters/rendering.ts | Templates hardcodeados de las páginas de artefacto y use-case, panels de test, tabla de propiedades, definiciones de métodos. Acá se editan los estilos visuales. | | src/reporters/generate-domain-documentation.ts | Orquestador del pipeline domain: load → transform → render → write | | src/reporters/generate-use-cases-documentation.ts | Orquestador del pipeline use-cases | | src/reporters/data-loading.ts | Carga de artifacts, JSDoc, test results, frontmatter de .md (y definition.yaml legacy) | | src/reporters/data-transformation.ts | Enriquecimiento: match JSDoc ↔ artifacts, merge de datos | | src/reporters/file-writing.ts | Escritura de archivos .md generados | | src/reporters/types.ts | Tipos compartidos entre todas las capas | | src/scripts/labels.ts | Labels HTML para tags (type, model status, test status) | | src/scripts/markdown.ts | Utilidades de formato markdown | | templates/track-artifacts-script.ts | Template del script que descubre artefactos del dominio |

Detalle de archivos — Capa 2

| Archivo | Función | |---|---| | templates/documentation/docusaurus.config.ts | Config del sitio: título, navbar, footer, Mermaid | | templates/documentation/src/css/custom.css | Variables de color, estilos globales | | templates/documentation/src/pages/index.tsx | Landing page | | templates/documentation/src/pages/index.module.css | Estilos de la landing page | | templates/documentation/sidebars.ts | Configuración de sidebar | | templates/documentation/static/ | Assets estáticos (imágenes, favicon) |

Scripts de desarrollo

# Terminal A — Arranca el servidor (solo una vez)
./bootstrap_fixture.sh
# → Genera docs del fixture, copia scaffold Docusaurus, instala deps, inicia en http://localhost:3000

# Terminal B — Regenera los .md después de editar archivos de Capa 1
./regenerate_fixture_docs.sh
# → Docusaurus hace hot-reload automático en el navegador

| Editaste... | Comando | |---|---| | src/reporters/rendering.ts | ./regenerate_fixture_docs.sh | | src/reporters/generate-*.ts | ./regenerate_fixture_docs.sh | | src/reporters/data-*.ts | ./regenerate_fixture_docs.sh | | src/reporters/file-writing.ts | ./regenerate_fixture_docs.sh | | src/scripts/labels.ts | ./regenerate_fixture_docs.sh | | src/scripts/markdown.ts | ./regenerate_fixture_docs.sh | | templates/documentation/src/** | Nada (hot-reload automático) | | templates/documentation/docusaurus.config.ts | Nada (hot-reload automático) | | Archivos nuevos en templates/documentation/ | Borrar __fixtures__/minimal-project/documentation/ y re-ejecutar ./bootstrap_fixture.sh |

Documentación detallada

Para una explicación completa de la arquitectura y el flujo de trabajo, consultá: docs/developer-workflow.md