@archi-code/ddd 0.0.0-stage → 3.0.0-alpha.2

package/ddd-skills/ddd-auditoria-refactorizacion/scripts/scan_ddd_smells.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""
+Escaneo heurístico de síntomas DDD en un repositorio TypeScript.
+
+Uso:
+    python3 scan_ddd_smells.py <ruta> [--json salida.json] [--domain-dir domain]
+
+Solo lee ficheros. Los hallazgos son indicios que hay que confirmar leyendo el código.
+"""
+import argparse
+import json
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+INFRA_PACKAGES = (
+    "express", "fastify", "koa", "@nestjs/", "@prisma/client", "prisma", "typeorm", "sequelize",
+    "mongoose", "mongodb", "pg", "mysql", "mysql2", "knex", "drizzle-orm", "@mikro-orm/", "axios",
+    "node-fetch", "kafkajs", "amqplib", "@azure/", "aws-sdk", "@aws-sdk/", "redis", "ioredis",
+)
+IGNORED_DIRS = {"node_modules", "dist", "build", ".git", "coverage", ".next", ".tmp"}
+
+IMPORT_RE = re.compile(r"""^\s*import\s+(?:[^'"]+\s+from\s+)?['"]([^'"]+)['"]""", re.M)
+REQUIRE_RE = re.compile(r"""require\(\s*['"]([^'"]+)['"]\s*\)""")
+SETTER_RE = re.compile(r"^\s*(?:public\s+)?set\s*([A-Z]\w*)\s*\(|^\s*(?:public\s+)?set\s+\w+\s*\(", re.M)
+PUBLIC_MUTABLE_FIELD_RE = re.compile(r"^\s*public\s+(?!readonly)(?!static)\w+\??\s*:", re.M)
+CLASS_RE = re.compile(r"\bclass\s+(\w+)")
+ORM_DECORATOR_RE = re.compile(r"@(Entity|Column|PrimaryGeneratedColumn|OneToMany|ManyToOne|Table|Prop|Schema)\b")
+PRIMITIVE_MONEY_RE = re.compile(r"\b_?(price|amount|total|importe|precio)\s*\??\s*:\s*number\b", re.I)
+PRIMITIVE_STATUS_RE = re.compile(r"\b_?(status|estado|state)\s*\??\s*:\s*string\b", re.I)
+SMELLY_NAME_RE = re.compile(r"\bclass\s+\w*(Manager|Helper|Utils?|Processor)\b")
+REPO_CLASS_RE = re.compile(r"\b(?:class|interface)\s+(\w+)Repository\b")
+# Cualquier receptor que guarde: this.orders.save(...), orderRepository.save(...), repo.persist(...)
+SAVE_CALL_RE = re.compile(r"(?:this\.)?(\w+)\s*\.\s*(?:save|add|persist|remove)\s*\(")
+NOT_A_REPOSITORY = {"events", "eventbus", "bus", "outbox", "inbox", "list", "set", "map", "array", "items", "tags"}
+ARCHI_OUTER_LAYER_RE = re.compile(r"""['"]@archi-code/ddd/(application|infrastructure)['"]""")
+NEW_DATE_RE = re.compile(r"\bnew\s+Date\s*\(\s*\)")
+TRANSACTION_START_RE = re.compile(r"(\$transaction|\.transaction|\btx\.run|\.run|runInTransaction|withTransaction)\s*\(")
+# La transacción es del adaptador del repositorio: dominio y aplicación no abren, reciben ni manejan transacciones
+TRANSACTION_HANDLING_RE = re.compile(
+    r"\b(TransactionRunner|TransactionManager|UnitOfWork|unitOfWork|startSession|startTransaction|commitTransaction|"
+    r"abortTransaction|withTransaction|runInTransaction|inTransaction)\b|\$transaction\b|['\"`]\s*(BEGIN|COMMIT|ROLLBACK)\b"
+)
+
+
+def iter_ts_files(root: Path):
+    for p in root.rglob("*"):
+        if p.is_dir() or any(part in IGNORED_DIRS for part in p.parts):
+            continue
+        if p.suffix in (".ts", ".tsx", ".mts", ".cts") and not p.name.endswith(".d.ts"):
+            yield p
+
+
+def zone_of(path: Path, domain_dir: str):
+    parts = [p.lower() for p in path.parts]
+    for zone in (domain_dir, "application", "infrastructure", "interfaces"):
+        if zone in parts:
+            return zone
+    return None
+
+
+def context_of(path: Path):
+    parts = list(path.parts)
+    for anchor in ("contexts", "bounded-contexts", "modules"):
+        if anchor in parts:
+            i = parts.index(anchor)
+            if i + 1 < len(parts):
+                return parts[i + 1]
+    return None
+
+
+def transaction_blocks(text: str):
+    """Devuelve (posición, contenido) de cada llamada transaccional, emparejando paréntesis."""
+    for m in TRANSACTION_START_RE.finditer(text):
+        if m.group(1) == ".run" and not re.search(r"(tx|transaction|uow|unitOfWork)\w*\s*$", text[:m.start()], re.I):
+            continue                                  # .run( de otra cosa
+        i = m.end() - 1                               # posición del '('
+        depth, j = 0, i
+        while j < len(text):
+            c = text[j]
+            if c == "(":
+                depth += 1
+            elif c == ")":
+                depth -= 1
+                if depth == 0:
+                    break
+            j += 1
+        yield m.start(), text[i:j + 1]
+
+
+def class_spans(text: str):
+    """Devuelve (inicio, fin, nombre) de cada clase: desde su declaración hasta la siguiente o el final."""
+    starts = [(m.start(), m.group(1)) for m in CLASS_RE.finditer(text)]
+    for k, (start, name) in enumerate(starts):
+        end = starts[k + 1][0] if k + 1 < len(starts) else len(text)
+        yield start, end, name
+
+
+def line_of(text: str, idx: int) -> int:
+    return text.count("\n", 0, idx) + 1
+
+
+def scan(root: Path, domain_dir: str):
+    findings = []
+    stats = defaultdict(int)
+    repos = []
+
+    def add(rule, severity, path, line, detail):
+        findings.append({"rule": rule, "severity": severity, "file": str(path.relative_to(root)), "line": line, "detail": detail})
+
+    for path in iter_ts_files(root):
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        stats["ficheros_ts"] += 1
+        zone = zone_of(path, domain_dir)
+        ctx = context_of(path)
+        is_test = ".test." in path.name or ".spec." in path.name
+
+        imports = [(m.group(1), m.start()) for m in IMPORT_RE.finditer(text)] + \
+                  [(m.group(1), m.start()) for m in REQUIRE_RE.finditer(text)]
+
+        if zone == domain_dir and not is_test:
+            stats["ficheros_dominio"] += 1
+            for mod, idx in imports:
+                if any(mod == p or mod.startswith(p if p.endswith("/") else p + "/") or mod == p.rstrip("/") for p in INFRA_PACKAGES):
+                    add("dominio-importa-infraestructura", "alta", path, line_of(text, idx), f"importa '{mod}'")
+                if not mod.startswith("@archi-code/") and re.search(r"/(infrastructure|interfaces|application)(/|$)", mod):
+                    add("dominio-importa-capa-exterior", "alta", path, line_of(text, idx), f"importa '{mod}'")
+            for m in ARCHI_OUTER_LAYER_RE.finditer(text):
+                add("dominio-importa-capa-exterior-del-paquete", "alta", path, line_of(text, m.start()),
+                    f"importa @archi-code/ddd/{m.group(1)}")
+            if "process.env" in text:
+                add("dominio-lee-entorno", "media", path, line_of(text, text.index("process.env")), "usa process.env")
+            for m in ORM_DECORATOR_RE.finditer(text):
+                add("decorador-orm-en-dominio", "alta", path, line_of(text, m.start()), f"@{m.group(1)}")
+            for m in SETTER_RE.finditer(text):
+                add("setter-en-dominio", "media", path, line_of(text, m.start()), m.group(0).strip()[:60])
+            for m in PUBLIC_MUTABLE_FIELD_RE.finditer(text):
+                add("campo-publico-mutable", "media", path, line_of(text, m.start()), m.group(0).strip()[:60])
+            for m in PRIMITIVE_MONEY_RE.finditer(text):
+                add("dinero-como-number", "media", path, line_of(text, m.start()), m.group(0))
+            for m in PRIMITIVE_STATUS_RE.finditer(text):
+                add("estado-como-string", "baja", path, line_of(text, m.start()), m.group(0))
+
+        if zone in (domain_dir, "application") and not is_test:
+            for m in NEW_DATE_RE.finditer(text):
+                add("new-date-en-dominio-o-aplicacion", "media", path, line_of(text, m.start()),
+                    "usa new Date(); inyecta un Clock")
+
+        if zone == "interfaces" and not is_test:
+            if re.search(r"Repository\b", text):
+                for m in re.finditer(r"\w+Repository\b", text):
+                    add("interfaz-usa-repositorio", "media", path, line_of(text, m.start()), m.group(0))
+                    break
+            for m in re.finditer(r"\bprisma\.\w+\.(create|update|delete|upsert)", text):
+                add("controlador-escribe-en-bd", "alta", path, line_of(text, m.start()), m.group(0))
+
+        if ctx and not is_test:
+            for mod, idx in imports:
+                target_ctx = None
+                if mod.startswith("."):
+                    target_ctx = context_of((path.parent / mod).resolve())
+                else:
+                    m = re.search(r"contexts/([\w-]+)/", mod)
+                    target_ctx = m.group(1) if m else None
+                if target_ctx and target_ctx != ctx:
+                    add("importacion-entre-contextos", "alta", path, line_of(text, idx), f"{ctx} importa de {target_ctx}")
+
+        for m in SMELLY_NAME_RE.finditer(text):
+            add("clase-con-nombre-generico", "baja", path, line_of(text, m.start()), m.group(0))
+
+        for m in REPO_CLASS_RE.finditer(text):
+            repos.append((m.group(1), str(path.relative_to(root))))
+
+        multi_save_blocks = []
+        if not is_test:
+            for start, block in transaction_blocks(text):
+                saved = {m.group(1).lower() for m in SAVE_CALL_RE.finditer(block)} - NOT_A_REPOSITORY
+                if len(saved) >= 2:
+                    multi_save_blocks.append(start)
+                    add("varios-agregados-en-una-transaccion", "alta", path, line_of(text, start),
+                        f"el mismo bloque transaccional guarda con {sorted(saved)}")
+
+        if zone in (domain_dir, "application") and not is_test:
+            m = TRANSACTION_HANDLING_RE.search(text)
+            if m is None:
+                m = next((TRANSACTION_START_RE.search(text, s) for s, _ in transaction_blocks(text)), None)
+            if m is not None:
+                rule = "transaccion-en-dominio" if zone == domain_dir else "transaccion-en-aplicacion"
+                severity = "alta" if zone == domain_dir else "media"
+                add(rule, severity, path, line_of(text, m.start()),
+                    f"maneja transacciones ({m.group(0).strip()[:40]}); muévelo al adaptador del repositorio")
+
+        if zone == "application" and not is_test:
+            for start, end, name in class_spans(text):
+                if any(start <= b < end for b in multi_save_blocks):
+                    continue
+                saved = {m.group(1).lower() for m in SAVE_CALL_RE.finditer(text, start, end)} - NOT_A_REPOSITORY
+                if len(saved) >= 2:
+                    add("caso-de-uso-guarda-varios-agregados", "alta", path, line_of(text, start),
+                        f"{name} guarda con {sorted(saved)}")
+
+        if not is_test and zone in ("application", None):
+            for cm in CLASS_RE.finditer(text):
+                if cm.group(1).endswith("Service"):
+                    methods = len(re.findall(r"^\s+(?:public\s+|async\s+)+\w+\s*\(", text, re.M))
+                    loc = text.count("\n")
+                    if methods > 15 or loc > 400:
+                        add("servicio-grande", "media", path, line_of(text, cm.start()),
+                            f"{cm.group(1)}: ~{methods} métodos, {loc} líneas")
+
+    part_names = ("Line", "Item", "Detail", "Address", "Linea", "Detalle", "Direccion")
+    for name, f in sorted(set(repos)):
+        if name.endswith(part_names):
+            findings.append({"rule": "repositorio-de-parte-interna", "severity": "media", "file": f, "line": 1,
+                             "detail": f"{name}Repository: ¿es una parte de otro agregado?"})
+    stats["repositorios"] = len(set(r[0] for r in repos))
+    return findings, dict(stats)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("root")
+    ap.add_argument("--json", dest="json_out")
+    ap.add_argument("--domain-dir", default="domain")
+    args = ap.parse_args()
+
+    root = Path(args.root).resolve()
+    if not root.is_dir():
+        print(f"No existe el directorio: {root}", file=sys.stderr)
+        sys.exit(2)
+
+    findings, stats = scan(root, args.domain_dir.lower())
+    order = {"critica": 0, "alta": 1, "media": 2, "baja": 3}
+    findings.sort(key=lambda f: (order.get(f["severity"], 9), f["rule"], f["file"], f["line"]))
+
+    by_rule = defaultdict(int)
+    for f in findings:
+        by_rule[(f["severity"], f["rule"])] += 1
+
+    print(f"Repositorio: {root}")
+    print("Estadísticas: " + ", ".join(f"{k}={v}" for k, v in stats.items()))
+    if stats.get("ficheros_dominio", 0) == 0:
+        print("Aviso: no se ha encontrado ninguna carpeta 'domain'. Las reglas de dominio no se han aplicado;"
+              " usa --domain-dir si se llama de otra forma, o revisa a mano.")
+    print("\nResumen por regla:")
+    for (sev, rule), n in sorted(by_rule.items(), key=lambda x: (order.get(x[0][0], 9), x[0][1])):
+        print(f"  [{sev:5}] {rule}: {n}")
+    print("\nPrimeros hallazgos:")
+    for f in findings[:40]:
+        print(f"  [{f['severity']:5}] {f['rule']}  {f['file']}:{f['line']}  {f['detail']}")
+    if len(findings) > 40:
+        print(f"  ... y {len(findings) - 40} más (usa --json para la lista completa)")
+
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps({"stats": stats, "findings": findings}, ensure_ascii=False, indent=2), encoding="utf-8")
+        print(f"\nJSON escrito en {args.json_out}")
+
+
+if __name__ == "__main__":
+    main()

package/ddd-skills/ddd-context-mapping/GUIA.md

@@ -0,0 +1,83 @@
+# Context Mapping
+
+> Parte del skill `archi-code-ddd`: léela solo cuando ese skill te dirija aquí. Los ejemplos están escritos con la API de `@archi-code/ddd` (las clases de su `src`) y se copian tal cual; las guías son la fuente de verdad: el paquete solo se aparta de ellas donde lo marca `[Fuera de los libros: convención de @archi-code/ddd]`, y cualquier otra discrepancia es un defecto del paquete.
+>
+> **Cuándo consultar esta guía.** Context Mapping de DDD para decidir cómo se integran en el código los Bounded Contexts. Cubre los patrones de integración entre modelos (Shared Kernel, Conformist, Anticorruption Layer, Open Host Service, Published Language, Separate Ways, Big Ball of Mud), upstream y downstream, estilos de integración (RPC, REST, mensajería con eventos), contratos e idioma publicado, idempotencia, consistencia eventual entre contextos, procesos de larga duración y cómo implementar una capa anticorrupción en TypeScript. Consúltala siempre que haya que conectar dos sistemas, servicios o módulos, integrar con un ERP, CRM, pasarela o sistema heredado, decidir entre llamada síncrona y eventos, diseñar una API pública entre servicios, o cuando un modelo empiece a copiar conceptos de otro, aunque no se mencione "context map".
+
+## Con @archi-code/ddd
+
+[Fuera de los libros: convención de @archi-code/ddd]
+
+* El paquete no trae capa anticorrupción, Open Host Service ni Published Language: se escriben en el proyecto sobre sus clases y puertos. El puerto hacia otro contexto (`ProductPricing`) es una interfaz en `domain/` que recibe y devuelve value objects (`Sku`, un `Composite` `SellableProduct`); adaptador (`CatalogHttpProductPricing`) y traductor (`CatalogTranslator`) van en `infrastructure/` y lanzan una `InfrastructureException` con código propio (`CAT001`), que el punto de entrada traduce por su código (`CAT001` → 503 en HTTP; sin traducción propia, `ExceptionClassifier.classify` la clasifica como `ExceptionKind.Internal`).
+* Un webhook entrante es un punto de entrada en `interfaces/` que traduce el lenguaje del emisor a la entrada de un `UseCase` y responde según el `ExceptionKind` que devuelve `ExceptionClassifier.classify(error)` (de `@archi-code/ddd/infrastructure`).
+* Los mensajes entre contextos viajan como `SerializedEvent` plano (`{ eventName, eventId, occurredOn, ...datos }`, con la identidad del agregado entre los datos, como `orderId`) por un `EventChannel` (tu canal de broker o de outbox), no con el envoltorio de IDDD `{ notificationId, typeName, version, occurredOn, event }`: `eventName` hace de `typeName` (`'sales.order.OrderPlaced'`) y también identifica la versión del contrato (una versión incompatible se publica con otro nombre, como `'sales.order.OrderPlacedV2'`), y `eventId` identifica el mensaje para deduplicar. No hay `notificationId` secuencial: si un feed REST lo necesita, lo asigna tu canal duradero.
+* Lo que sale se traduce al Published Language en infraestructura, con un `EventChannel` propio en el adaptador del broker (`ContractPublishingChannel` + `SalesContracts`, en `ddd-skills/ddd-eventos-dominio/references/publicacion-ts.md`); nunca se publica fuera del contexto un evento interno tal cual (`{ ...event }`).
+* Lo que entra de otro contexto se lee con una clase propia `extends EventBase` que lleva el nombre publicado y solo los campos que este contexto usa; la factoría de `EventRegistry` es el traductor, y un `EventListener` con `@ListensTo(Evento, { consumer })` ejecuta un caso de uso, que valida cada campo con value objects en `toCommand`.
+* Los procesos entre contextos se encadenan con eventos y listeners, cada uno con su caso de uso.
+
+Una línea entre dos Bounded Contexts significa **integración técnica** y **traducción entre dos lenguajes** [Destilado cap. 4]. Esta guía decide el tipo de cada línea y cómo se implementa.
+
+
+## Flujo de trabajo
+
+### Paso 1. Elegir el patrón de integración para cada relación
+
+Para cada par de contextos que se relacionan, anota quién es upstream (U, de quien depende el otro) y quién downstream (D) [Destilado cap. 4]. Resumen [Destilado cap. 4]:
+
+| Patrón | Esencia |
+|---|---|
+| Shared Kernel | Pequeño modelo común compartido por acuerdo explícito. Difícil de mantener; se evita si es posible [IDDD cap. 2] |
+| Conformist | El downstream adopta el modelo upstream tal cual |
+| Anticorruption Layer | El downstream traduce entre el modelo upstream y el suyo; la opción más defensiva |
+| Open Host Service | El upstream ofrece un protocolo abierto, documentado y cómodo para cualquier integrador |
+| Published Language | Formato de intercambio documentado (JSON Schema, Protobuf, Avro); suele ir con OHS |
+| Separate Ways | No integrar: la integración no aporta lo suficiente |
+| Big Ball of Mud | Sistema sin fronteras; si hay que integrarse, siempre con ACL y sin hablar su lenguaje |
+
+Árbol de decisión rápido `[Fuera de los libros: síntesis de las definiciones]`:
+
+1. ¿La integración aporta valor real? No → Separate Ways.
+2. ¿Eres downstream? Entonces:
+   * ¿El upstream es un Big Ball of Mud o un producto externo? → ACL, siempre.
+   * ¿Tu contexto es Core? → ACL, salvo coste desproporcionado.
+   * ¿El upstream ofrece OHS con Published Language y su modelo se parece al tuyo? → Conformist puede ser aceptable.
+3. ¿Eres upstream con varios consumidores? → Open Host Service con Published Language.
+4. ¿La tentación es compartir clases o tablas? → Para y revisa: casi siempre se resuelve mejor con Published Language.
+
+### Paso 2. Elegir el estilo de integración
+
+Vernon los ordena de menos a más robusto: RPC, REST, mensajería [Destilado cap. 4]. Detalle en `ddd-skills/ddd-context-mapping/references/estilos-integracion.md`.
+
+Reglas que aplican siempre:
+
+* **Integración por base de datos o ficheros:** evitarla. Si es inevitable, aislar el modelo con ACL [Destilado cap. 4].
+* **Asume los principios de la computación distribuida:** la red falla, hay latencia, el ancho de banda no es infinito, la red no es segura, la topología cambia, hay varios administradores, el transporte cuesta y la red es heterogénea [IDDD cap. 13].
+* **Evita los choques de trenes de integración:** si C0 hace una petición bloqueante a C1, C1 no debe hacer a su vez una petición bloqueante a S1 para responderla. Usa mensajería [Destilado cap. 4].
+* **Recursos REST sintéticos:** diseñados para los casos de uso del cliente, no como espejo de los agregados. Exponer el modelo tal cual obliga a todos a ser Conformist [Destilado cap. 4; IDDD cap. 13].
+* **Los consumidores dependen del esquema, no de las clases del productor.** Leen el Published Language (por ejemplo JSON) y lo traducen a sus propios tipos [Destilado cap. 4; IDDD cap. 13].
+* **Mensajería:** el mecanismo debe garantizar entrega al menos una vez y el receptor debe ser idempotente [Destilado cap. 4].
+* **Estado remoto mínimo:** copia solo los atributos que tu modelo necesita y modélalos con tus conceptos. Si no, tu `ProductOwner` acaba siendo un `User` disfrazado [IDDD cap. 3].
+* **La indisponibilidad se modela:** "todavía no está" es un estado válido del dominio, no un error. IDDD lo resuelve con un estado explícito en un value object [IDDD cap. 3].
+
+### Paso 3. Diseñar la traducción
+
+Para cada relación con ACL, define puerto, adaptador y traductor. Implementación con `@archi-code/ddd` (puerto con value objects, adaptador HTTP, webhook entrante, eventos de otro contexto y Published Language de salida) en `ddd-skills/ddd-context-mapping/references/anticorrupcion-ts.md`.
+
+Para cada evento que cruza un contexto, decide entre **evento enriquecido** (más autonomía del consumidor, pero difícil prever todo y riesgo de exponer datos sensibles) o **evento ligero con consulta al origen** (query-back), o una mezcla [Destilado cap. 4].
+
+## Señales de alarma
+
+* Un contexto importa tipos (clases, interfaces, enums) del dominio de otro.
+* Tablas compartidas entre contextos.
+* API REST que devuelve el agregado serializado con todos sus campos.
+* Una petición de usuario que atraviesa tres servicios en cadena de forma síncrona.
+* Un consumidor de eventos sin control de duplicados.
+* Un contexto publica hacia fuera sus eventos internos tal cual (`{ ...event }`), o un listener recibe la clase de evento de otro contexto importada de su código.
+* "Shared Kernel" usado como excusa para compartir una librería de modelos que crece sin acuerdo [IDDD cap. 13].
+* El código copia sin traducir el modelo de un proveedor.
+
+## Siguiente guía
+
+* Estructura interna de cada contexto y dónde vive el ACL → `ddd-skills/ddd-arquitectura/GUIA.md`.
+* Diseño de los eventos que se publican → `ddd-skills/ddd-eventos-dominio/GUIA.md`.
+* Consistencia eventual entre agregados y procesos → `ddd-skills/ddd-agregados/GUIA.md`.