Archprint

Archprint

Descubre las reglas de arquitectura que tu repositorio ya aplica, con la evidencia adjunta.

Pruébalo en tu navegador, sin instalar nada · Inicio rápido · Úsalo en CI · Úsalo con agentes de IA · Documentación

Qué hace, en palabras sencillas

Todo código tiene reglas no escritas. "Las páginas nunca hablan directamente con la base de datos." "El código compartido nunca vuelve a la aplicación." Nadie las escribió, pero el código las sigue, hasta que un día alguien (o un asistente de IA) rompe una sin darse cuenta.

Archprint lee un proyecto TypeScript, encuentra las reglas que su código ya sigue y te muestra la prueba de cada una: cuántos archivos la cumplen, qué archivos la rompen y qué tan seguro está. Las reglas en las que confías se convierten en comprobaciones automáticas en las herramientas que tu equipo ya usa, de modo que una infracción se detecta la próxima vez que se ejecute el linter (en tu editor, un hook de pre-commit o CI), no semanas después en la revisión.

Piénsalo como un inspector de edificios que primero inspecciona la casa y anota cómo se construyó realmente, en lugar de entregarte un manual de reglas de otro lugar.

• Para desarrolladores y líderes técnicos: reglas de lint inferidas y respaldadas por evidencia para ESLint y dependency-cruiser, generadas con init, conectadas con wire y eliminadas con eject.
• Para revisores: archprint check marca solo las infracciones de reglas que introduce un pull request, en línea en GitHub, nunca el backlog existente.
• Para equipos que usan agentes de codificación con IA: Claude Code, Cursor y otros agentes pueden preguntarle a Archprint por las reglas del proyecto, con la evidencia, antes de escribir código.
• Para cualquiera que evalúe un código: una imagen rápida y honesta de cómo está estructurado realmente un proyecto.

Tu CLAUDE.md es orientación. Tus reglas de lint son aplicación. Archprint cierra la brecha generando la aplicación a partir de patrones que tu código ya demuestra, para que adoptes reglas en las que puedas confiar en lugar de redactarlas a mano.

Míralo en acción

Las grabaciones a continuación usan archprint-demo, una API pequeña de Next.js cuyas rutas llegan a la base de datos solo a través de una capa de servicios.

1. Encuentra las reglas que tu código ya sigue. Cada regla viene con su evidencia.

2. Ve por qué se confía en una regla. La comprobación de confianza, paso a paso.

3. Activa las reglas, observa cómo se detecta una infracción y elimínalo todo de nuevo. Archprint escribe sus archivos, agrega una línea a tu configuración de ESLint, el lint marca una ruta que importa la base de datos directamente y eject restaura tu proyecto exactamente.

Pruébalo tú mismo, sin instalar nada: abre la demo en StackBlitz. El escaneo se ejecuta en cuanto se abre, y el README de la demo te guía para aplicar una regla en ESLint, romperla y pedir las reglas a través de MCP.

Úsalo con agentes de codificación con IA

Los agentes de codificación con IA pueden preguntarle a Archprint por las reglas de un proyecto a través de MCP, un estándar abierto que permite a los agentes usar herramientas externas. Preguntas en palabras sencillas; el agente llama a Archprint por su cuenta y responde con la evidencia. Archprint solo informa. La aplicación sigue ejecutándose en tu linter.

Claude Code lista las reglas con lo que se aplica y lo que se mantiene para revisión, luego agrega una ruta y verifica su propio cambio con archprint antes de informar:

Cursor funciona de la misma manera. En estas grabaciones, Cursor estaba configurado con Grok 4.7, no Claude. En el chat de la aplicación de escritorio, su agente llamó a la herramienta de escaneo de Archprint por su cuenta; esta captura muestra el resultado de la herramienta y la respuesta:

En la terminal (cursor-agent), hace lo mismo: lista las reglas, luego agrega la ruta y la verifica con archprint_check:

Medido: la misma pregunta con y sin Archprint

Le preguntamos a Claude Code (Opus 5.5) "¿Qué reglas de arquitectura sigue ya este repositorio?" en la aplicación demo (70 archivos), cinco ejecuciones de cada manera. Mediana [rango]:

	Sin Archprint	Con Archprint
Tokens leídos	81k [58k a 96k]	52k [52k a 52k]
Tokens escritos	1.1k [1.1k a 1.4k]	0.6k [0.6k a 0.6k]
Costo por pregunta	$0.083 [$0.078 a $0.153]	$0.037 [$0.032 a $0.076]
Tiempo	17 s [15 a 19]	10 s [9 a 31]
Llamadas a herramientas	5 [4 a 10]	2 [2 a 2]

Lo que mostraron las respuestas:

• Ambas encontraron la regla principal: las rutas llegan a la base de datos solo a través de lib/services/.
• Con Archprint, cada ejecución dio la evidencia de cada regla y nombró el único archivo que rompe una (lib/db.ts lee process.env fuera de la capa de configuración). Ninguna ejecución sin él lo notó.
• Sin Archprint, Claude también describió convenciones de nomenclatura que Archprint no verifica.

Lee estos números con cuidado: alrededor de 50k de los tokens leídos en ambas columnas son el propio prompt del sistema de Claude Code, y este es un repositorio pequeño; los más grandes aún no se han medido. Método, entorno y cada respuesta.

La configuración para Claude Desktop, Claude Code, Cursor y otros clientes está en Configuración de MCP.

Inicio rápido

Requiere Node 20 o superior. Ejecuta estos comandos en una carpeta con un tsconfig.json. En un monorepo, scan y recommend también aceptan la raíz y cubren cada aplicación, mientras que init y generate funcionan en una aplicación a la vez (por ejemplo, apps/web); en una raíz con varias aplicaciones, se detienen, listan las aplicaciones y te piden que vuelvas a ejecutar con una.

# 1. See the rules your code already follows, with the evidence. Changes nothing.
npx archprint scan .

# 2. Ask why one rule is trusted (use a rule label from the scan)
npx archprint explain AP-001 .

# 3. Set up enforcement for the rules your code already follows cleanly,
#    and record what to review or adopt next in .archprint/config.json
npx archprint init .

# 4. Connect the generated rules to your ESLint / dependency-cruiser config (one managed line)
npx archprint wire

# 5. Run your linter as usual. Your code passes today; a new import that breaks a rule fails.
npx eslint .

# To undo everything, exactly:
npx archprint eject

Míralo detectar algo. Después del paso 4, rompe una regla a propósito: por ejemplo, haz que un archivo de ruta importe tu cliente de base de datos directamente y luego ejecuta tu linter. Ese es el ciclo completo que la demo recorre en el navegador.

Para mantenerlo en el proyecto en lugar de usar npx: npm install --save-dev archprint.

Más comandos para una configuración deliberada, paso a paso:

# Inspect the evidence behind one rule
archprint explain AP-002 apps/web

# Write the auto-trusted (mechanical) rules to .archprint/, only for the linters your repo uses.
# Structural-inference rules are held for review; add --include-structural to emit them too.
archprint generate apps/web

# Confirm the generated rules pass on your repo before wiring
archprint generate apps/web --check

# Generate a single rule by id after reviewing it (including a SUGGEST rule)
archprint generate apps/web --rule AP-001

# Recommend a rule set from the evidence and the detected stack (fresh repos too)
archprint recommend apps/web

# Upgrading from 0.5.x? Move an older archprint-rules/ setup to the .archprint layout
archprint migrate

O compila desde el código fuente:

git clone https://github.com/Tommkruix/archprint
cd archprint
npm ci
npm run build
node dist/cli.js scan <path-to-your-app>

Cómo decide en qué confiar

Archprint es deliberadamente cauteloso: una regla incorrecta duele más que ninguna regla. Cada regla candidata pasa dos comprobaciones antes de activarse para ti.

1. ¿Hay suficiente evidencia? Ver que 5 de 5 archivos siguen un patrón no es prueba; 40 de 40 sí lo es. Archprint puntúa cada regla con un límite inferior de Wilson, una medida estadística estándar que combina la frecuencia con la que se cumple la regla con la cantidad de archivos en los que se verificó. Cada regla cae en uno de tres grupos:

• AUTO (aplicable): el límite inferior del 95% de conformidad es al menos 90%, con como máximo 3 excepciones y un rol clasificado con confianza.
• SUGGEST (provisional): el patrón se cumple en al menos el 80% de los archivos y el rol tiene al menos un 50% de certeza, pero falla una condición de AUTO: el piso de confianza está por debajo del 90% (demasiados pocos archivos, o demasiados que lo rompen), más de 3 archivos lo rompen, o el rol tiene menos del 80% de certeza. Se muestra para revisión, no se genera automáticamente.
• REJECT: no hay suficiente señal.

2. ¿Podría la regla en sí ser incorrecta? Una regla puede pasar los números y aun así ser incorrecta si Archprint adivinó mal el propósito de una carpeta. Por eso solo las familias mecánicas, que se basan en señales inequívocas, se confían sin revisión: importaciones prohibidas (AP-001, AP-002), dependencias circulares, aislamiento de pruebas, estilo de importación, aislamiento de console y barriles de API pública. Una auditoría de corrección adversarial (tres rondas sobre cuatro repositorios reales) encontró cero falsos positivos en estas en cada ronda. Todas, excepto las dependencias circulares, se escriben como reglas de lint; para ciclos, Archprint informa el resultado pero aún no escribe una regla.

Las familias estructurales infieren una "capa" o "rol" a partir de las rutas, lo que puede ser incorrecto (límites de capa y rol, separación UI/datos, pureza de entrada, servidor/cliente, aislamiento de feature-slice y aplicación, acceso a env, API de paquetes del workspace, aislamiento de stories). La higiene de dependencias, cuya aplicación puede marcar de más, y la declaración de dependencias también se mantienen en espera. Todas estas se mantienen para tu revisión por defecto y se escriben como aplicación solo con --include-structural, independientemente de su puntuación estadística, hasta que ganen el mismo historial limpio. Nada que pueda ser incorrecto se aplica sin que tú lo aceptes.

Las reglas generadas son verdes por construcción: cada una deja pasar los pocos archivos de excepción conocidos a partir de los cuales se infirió, por lo que adoptarla mantiene tu lint en verde mientras las nuevas infracciones aún se detectan, y una comprobación de autoconsistencia se niega a escribir una regla cuya evidencia no se sostenga. Para ejecutar las reglas generadas contra tu código antes de conectarlas, usa archprint generate --check.

Qué puede detectar

Se entrega como: Auto = activado como aplicación (familias mecánicas). Revisión = se mantiene para tu revisión por defecto; emítelo con --include-structural. Informe = solo se muestra, nunca se aplica.

Archprint reconoce la pila (Next.js, Nest, SvelteKit, Nuxt, Remix) y clasifica componentes de UI en React (.tsx), Angular (.component.ts, .directive.ts) y componentes de archivo único de Vue y Svelte (lee el bloque <script> de archivos .vue/.svelte), por lo que las reglas conscientes de componentes se aplican independientemente del framework.

Detector	Regla que puede inferir	Se incluye como
Importaciones prohibidas (AP-001, AP-002)	AP-001: un punto de entrada de solicitud (manejador de ruta) no debe importar el cliente de BD. AP-002: un punto de entrada de servidor no debe importar la capa de UI	Automático
Dependencias circulares	El grafo de módulos debe permanecer acíclico (condicionado a qué tan libre de ciclos ya está); se reporta, aún no se escribe ninguna regla de lint	Reporte
Aislamiento de pruebas	El código de producción (no de pruebas) no debe importar archivos de prueba o spec	Automático
Higiene de dependencias	Importar paquetes de terceros por su entrada pública, no por los internos de una dependencia src/internal	Revisión
Declaración de dependencias	Cada paquete de terceros importado debe declararse en package.json (sin dependencias fantasma/transitivas)	Revisión
Estilo de importación	Preferir alias de espacio de trabajo sobre importaciones relativas profundas (../../../)	Automático
Aislamiento de consola	El código de biblioteca (no CLI) no debe llamar a console.*	Automático
Límites de API pública (barrel)	Los archivos fuera de una característica o paquete deben importarlo a través de su barrel index, no importar profundamente sus internos	Automático
Límites de capa	Los archivos en una capa no deben importar otra, inferido de la dirección dominante de dependencias	Revisión
Capas por rol	Los niveles semánticos mantienen su dirección (un REPOSITORY no debe importar un SERVICE, un SERVICE no debe importar un CONTROLLER)	Revisión
Pureza de entradas	Las entradas de framework (páginas, rutas, layouts) no deben ser importadas por otro código de primera parte	Revisión
Separación UI / datos	Los componentes de UI reutilizables no deben importar la capa de BD/datos directamente	Revisión
Límite servidor / cliente	Un módulo "use client" de Next.js no debe importar un módulo server-only	Revisión
Aislamiento de slices de características	Los slices hermanos bajo un contenedor features/modules/slices/domains no deben importarse entre sí	Revisión
Aislamiento de aplicaciones	Las aplicaciones hermanas bajo un contenedor apps/services no deben importarse entre sí directamente	Revisión
Acceso a entorno	Leer process.env solo en la capa de configuración/entorno	Revisión
API de paquetes del espacio de trabajo	Importar un paquete del monorepo por su nombre, no por una ruta profunda a su código fuente	Revisión
Aislamiento de stories	Los archivos .stories de Storybook no deben ser importados por otro código	Revisión
Módulos huérfanos	Archivos que nada importa y que no son entradas de framework (candidatos a código muerto)	Reporte
Alcanzabilidad transitiva	Un límite de capa que una regla de importación simple pasa pero que se filtra a través de una capa intermedia	Reporte

recommend (y init) ordenan cada familia de reglas en niveles: reglas que tu código ya sigue (aplicar ahora), reglas que tu código sigue y que Archprint reporta pero aún no escribe (dependencias circulares hoy), reglas con evidencia débil (revisar y adoptar), y reglas que repositorios comparables suelen seguir pero el tuyo aún no (adoptar desde el primer día). Cada recomendación incluye la proporción de repositorios comparables (tu stack detectado, si no el general) que ya aplican esa regla, extraída de un censo de decenas de miles de repositorios públicos de TypeScript. Así, incluso un repositorio nuevo, con poco código del que aprender, obtiene una línea base consciente del stack respaldada por lo que el ecosistema realmente hace en lugar de valores predeterminados elegidos a mano.

Qué escribe en tu proyecto

archprint generate (y init) escribe .archprint/config.json más un archivo para cada linter que tu repositorio ya ejecuta y que tenga reglas que aplicar. Un proyecto típico de ESLint obtiene dos archivos, config.json y eslint.mjs; un repositorio cuyas reglas de dependency-cruiser también se adoptan obtiene un tercero. archprint detecta ESLint y dependency-cruiser, por lo que nunca te quedas con configuración para una herramienta que no tienes. --emit <eslint|dependency-cruiser|all> fuerza el formato.

• .archprint/config.json (siempre): la definición exacta de cada regla mecánica que adoptaste, con la evidencia registrada en la adopción y el modo de resolución en el que se generó (archprint check la lee, por lo que una verificación nunca vuelve a inferir una regla), las excepciones que permitiste con una razón, lo que se aplica, lo que solo se sigue pero se reporta, lo que se mantiene para revisión y lo que vale la pena adoptar, y la lista de salidas gestionadas que eject elimina.
• .archprint/eslint.mjs (cuando ESLint está presente): un archivo de configuración plana de ESLint autocontenido que incorpora cada regla inferida de ESLint (importaciones prohibidas basadas en marcadores, límites de estilo de importación no-restricted-imports, aislamiento de consola) y no necesita plugins adicionales: agrega reglas a tu configuración ESLint existente, que ya analiza tu TypeScript. Así puedes confirmarlo, publicarlo o entregarlo a otro repositorio y adoptarlo en una línea (import archprint from './.archprint/eslint.mjs'). Se auto-ignora **/.archprint/**. Las reglas de importación prohibida (AP-) se incluyen como un plugin ESLint local generado dentro de él, por lo que conectar la configuración de ESLint también las aplica, sin instalación adicional.
• .archprint/dependency-cruiser.json (cuando dependency-cruiser está presente): un conjunto de reglas forbidden con los límites mecánicos (importación profunda de API pública, aislamiento de pruebas); los que se mantienen para revisión (capa, capas por rol, slice de características, aislamiento de aplicaciones, pureza de entradas, internos de dependencias, dependencias fantasma) se agregan solo con --include-structural, después de que los revises.
• Una sección gestionada en tu README.md que resume lo que se aplica ahora, lo que solo se sigue pero se reporta, lo que se mantiene para revisión y lo que vale la pena adoptar (escrita por init, o generate --readme), más una entrada gestionada .prettierignore para que los archivos generados queden fuera de tu formateador.

--expand además escribe los artefactos granulares dentro de .archprint/: el JSON de ESLint y dependency-cruiser por familia, tarjetas por regla (.md) con fixtures que pasan y fallan, la configuración de element-types de eslint-plugin-boundaries, pruebas de ts-arch y el grafo de capas en Mermaid y Graphviz DOT.

Mantenerse sincronizado y salir limpiamente. Volver a ejecutar generate (o init) actualiza .archprint/ y elimina cualquier regla que la evidencia ya no respalde, por lo que la salida nunca se desvía del código. wire inserta una única referencia gestionada en cada herramienta de aplicación que tu repositorio use (una configuración plana de ESLint, un .dependency-cruiser.json), una que sobrevive a esas regeneraciones; para una configuración que no puede editar de forma segura (una configuración JS de dependency-cruiser, por ejemplo), imprime el fragmento exacto para pegar. eject elimina los archivos de Archprint y cada referencia conectada, restaurando cada configuración exactamente. generate --check ejecuta las reglas ESLint generadas contra tu repositorio y reporta si pasan, por lo que puedes confirmar antes de conectar. ¿Actualizando desde 0.5.x? archprint migrate mueve una configuración anterior de archprint-rules/ a este diseño y reconecta tus configuraciones en su lugar.

Uso en CI

archprint check reporta solo las violaciones que un cambio introduce, en comparación con una rama base, para las reglas que tu equipo adoptó con init o generate. El backlog existente nunca aparece, y cada hallazgo lleva su evidencia. Funciona en cualquier CI, y en GitHub muestra cada hallazgo en línea en la solicitud de extracción (míralo en una solicitud de extracción de demostración).

En GitHub, usa la Acción de verificación de archprint (en el GitHub Marketplace):

# .github/workflows/archprint.yml
name: archprint
on: pull_request
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: Tommkruix/archprint-action@v1

Verifica la solicitud de extracción en sí, por lo que no necesita un paso de checkout. La misma verificación en pasos simples, sin la Acción:

# .github/workflows/archprint.yml
name: archprint
on: pull_request
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npm ci
      - run: npx archprint check --base ${{ github.event.pull_request.base.sha }} --format github

• Advertencia por defecto. Agrega --fail-on new (o el fail-on: new de la Acción) para fallar el trabajo ante una nueva violación, luego marca el trabajo como una verificación de estado requerida en la protección de tu rama para que una solicitud de extracción que agregue una no pueda fusionarse.

• Solo reglas adoptadas. check lee las reglas adoptadas en .archprint/config.json, escritas por init y generate, y verifica solo las reglas mecánicas registradas allí, nunca las estructurales. Las reglas adoptadas en la misma solicitud de extracción se enumeran pero nunca se cuentan en su contra.

• Una excepción justificada necesita una razón. Cuando un archivo tiene una razón real para romper una regla, regístrala: npx archprint allow AP-001 app/api/health/route.ts --reason "Health check queries the database directly". Va en la lista allowed de .archprint/config.json, check deja de contarla y la enumera con su razón en la solicitud de extracción, y el próximo archprint generate evita que ESLint la marque. Una entrada sin razón se rechaza, y una entrada que el código ya no necesita se señala. Las reglas aplicadas a través de dependency-cruiser (API pública) no están cubiertas en ese lado aún.

• Eliminar reglas nunca es silencioso. Si una solicitud de extracción elimina .archprint/config.json, o las reglas en él, que la rama base tiene, check advierte y enumera cada regla que deja de verificarse. No falla el trabajo, porque eliminar una regla puede ser una decisión deliberada del equipo. Para que esa decisión necesite un revisor, agrega una entrada de CODEOWNERS y activa "Requerir revisión de Code Owners" en la protección de rama:

  /.archprint/ @your-team
  /.github/workflows/ @your-team
  

• Actualización: desde 0.8.x o anterior, ejecuta archprint generate una vez para registrar las reglas adoptadas. Hasta que lo hagas, check publica un aviso de que no se ejecutó y sale con 0. Las configuraciones de 0.9.0 a 0.11.x siguen funcionando como están: check aún lee su rules.json y allow.json, y el próximo generate mueve ambos a config.json.

• Otros sistemas de CI: --format json da salida con clave de versión, y el código de salida es el contrato: 0 ok, 1 nuevas violaciones con --fail-on new, 2 la configuración de CI es incorrecta (por ejemplo, un clon superficial sin el commit base). Verifica el historial completo (fetch-depth: 0 o el equivalente de tu CI).

• Seguro en solicitudes de extracción de forks. Solo necesita acceso de lectura, no usa secretos y nunca ejecuta tu código.

Configuración de MCP

archprint mcp ejecuta Archprint como un servidor MCP sobre stdio, para que un agente pueda preguntar qué reglas de arquitectura tu repositorio ya sigue, con la evidencia, antes de escribir código. Expone cuatro herramientas de solo lectura: archprint_scan, archprint_recommend, archprint_explain y archprint_check. Cada regla se devuelve expresada en palabras simples, con su evidencia, los archivos que la rompen y si archprint la aplica, la mantiene para revisión o solo la reporta. archprint_explain toma cualquier etiqueta de regla del escaneo (por ejemplo AP-002 o env-access). archprint_check reporta las reglas adoptadas que el cambio actual del agente rompe, incluyendo ediciones no confirmadas, para que pueda corregirlas antes de terminar. Apunta Claude Desktop, Claude Code, Cursor o cualquier cliente MCP a él:

{
  "mcpServers": {
    "archprint": { "command": "npx", "args": ["-y", "archprint", "mcp"] }
  }
}

Cosas que puedes preguntar a tu agente. No nombras las herramientas; el agente las elige:

• "¿Qué reglas de arquitectura sigue ya este repositorio?"
• "¿Qué archivo incumple la regla de acceso al entorno y cómo debería arreglarlo?"
• "Estoy añadiendo una nueva ruta de API. ¿Qué reglas debería seguir en este código base?"
• "¿Qué reglas deberíamos aplicar ahora y cuáles merece la pena adoptar?"

Tu código permanece en tu máquina. Este valor predeterminado es un servidor local: lee tu copia local, por lo que es el adecuado para código privado, y tu código fuente nunca sale de tu máquina, sea cual sea el host de git que uses.

Si el servidor no se inicia. Si el cliente dice que el servidor no se inició o que no se encontró npx, no puede ver el PATH de tu shell. Las aplicaciones de escritorio abiertas desde el Dock o el menú Inicio no lo cargan, lo cual es común cuando Node proviene de nvm o Homebrew. Una ruta completa a npx por sí sola no es suficiente, porque npx en sí necesita node en el PATH. Apunta ambos a la carpeta que imprime dirname "$(which node)", por ejemplo /opt/homebrew/bin:

{
  "mcpServers": {
    "archprint": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "archprint", "mcp"],
      "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }
    }
  }
}

Iniciar el editor desde una terminal también funciona, porque entonces hereda el PATH de tu shell.

Instalaciones en una línea. En Claude Code:

claude mcp add archprint -- npx -y archprint mcp

En Cursor, coloca el JSON anterior en .cursor/mcp.json en tu proyecto (o ~/.cursor/mcp.json para cada proyecto), luego habilita archprint en Configuración > MCP.

Escaneo de un repositorio público por URL. archprint mcp --http ejecuta un servidor remoto en su lugar. Clona el repositorio de forma superficial a un directorio temporal, ejecuta el mismo análisis de solo lectura, devuelve el resultado y elimina el clon (solo URLs públicas github.com, gitlab.com y bitbucket.org; no se escribe ni se conserva nada). Las herramientas toman entonces una URL repo (y un ref opcional). Escucha en 0.0.0.0:8848/mcp por defecto (establece --host 127.0.0.1 para mantenerlo en tu propia máquina, o --port/$PORT para cambiar el puerto) y responde a las comprobaciones de salud en /health (usa esta en Cloud Run, que reserva /healthz) y /healthz. Cada solicitud clona y escanea, por lo que un servidor al que cualquiera pueda acceder gasta cómputo en nombre de cualquiera: mantenlo detrás de autenticación, como el IAM de Cloud Run, a menos que aceptes ese costo.

Las herramientas son de solo lectura (nunca escriben en el repositorio); usa el generate/wire de la CLI para realmente emitir y aplicar reglas.

Cómo se compara

Las herramientas TypeScript establecidas (dependency-cruiser, eslint-plugin-boundaries, Nx, Sheriff, ts-arch) todas aplican reglas de arquitectura que escribes a mano. Archprint infiere esas reglas a partir del grafo de importación real y condiciona cada una a evidencia estadística antes de proponerla. Luego las emite en los formatos de esas herramientas, por lo que complementa tu stack en lugar de reemplazarlo.

Verificado contra la documentación de cada herramienta (ecosistema TypeScript). Las dos columnas que importan son las que ninguna otra herramienta TypeScript cubre:

Herramienta	Aplica reglas de arquitectura	Auto-infiera desde el grafo de importación	Adjunta evidencia estadística
Archprint	sí	sí	sí
dependency-cruiser	sí	no	no
eslint-plugin-boundaries	sí	no	no
@nx/enforce-module-boundaries	sí	no	no
Sheriff	sí	no	no
ts-arch	sí	no	no
madge / knip	solo análisis	no	no

Advertencia honesta: en otros ecosistemas, Tach (Python) y ArchLint (Java) sí auto-infieren límites de módulos, por lo que el nicho específico de Archprint es la auto-inferencia más la condicionamiento por evidencia estadística en el ecosistema TypeScript. Archprint también se superpone en detección con dependency-cruiser (ciclos, huérfanos, alcanzabilidad) y knip (código muerto); en lugar de competir, escribe las reglas que genera en los formatos de esas herramientas.

Comandos

• archprint init [path]: configuración sin configuración previa. Detecta el stack, aplica las reglas que el código ya sigue, y escribe .archprint/ más una sección README gestionada. Opciones: --expand, --include-structural, --out <dir>, --fast, --force.
• archprint scan [path]: informa de las reglas que el repositorio ya sigue, con evidencia. No cambia nada. --deep resuelve a través de barrels y alias.
• archprint explain <id> [path]: muestra el desglose de la compuerta para una regla, con un codeframe por excepción más cómo arreglarla, cuándo no usarla y cómo aplicarla.
• archprint recommend [path]: recomienda un conjunto de reglas a partir de la evidencia del repositorio y el stack detectado (funciona también en un repositorio nuevo), y nombra la herramienta instalada que aplicará cada regla que pueda escribir.
• archprint generate [path]: escribe las reglas mecánicas de confianza automática en .archprint/ para los linters que tu repositorio usa; las reglas estructurales se mantienen para revisión. --emit <eslint|dependency-cruiser|all> fuerza el formato, --only <family> y --rules <ids> reducen la salida, --check ejecuta las reglas generadas contra tu repositorio, --readme añade la sección README, --expand también escribe los archivos por familia, tarjetas, fixtures y el grafo, y --rule <id> emite una regla revisada. También --include-structural, --no-graph, --out <dir>, --fast.
• archprint check [path]: informa de las violaciones de tus reglas adoptadas que introduce un cambio, en comparación con --base <branch or commit>. Solo advertencia a menos que --fail-on new. --format text|json|github, --out <dir>. Ver Uso en CI.
• archprint allow <rule> <file> --reason "...": acepta una regla adoptada que se rompe en un archivo, con una razón, registrada en .archprint/config.json. check deja de contarla y la lista en la solicitud de extracción; generate detiene que ESLint la marque. --remove la retira.
• archprint wire: referencia las reglas generadas desde las herramientas de aplicación que tu repositorio usa (config plana de eslint, .dependency-cruiser.json) a través de una referencia gestionada y reversible. --out <dir>, --dry-run.
• archprint eject: elimina los archivos generados de Archprint, su configuración, la sección README gestionada y cualquier referencia conectada, restaurando cada configuración exactamente. --out <dir>, --dry-run.
• archprint migrate (alias upgrade): mueve una configuración más antigua de archprint-rules/ al diseño .archprint/ y reconecta tus configuraciones en su lugar. --dry-run.
• archprint mcp: ejecuta Archprint como un servidor MCP para que Claude, Cursor y otros agentes puedan llamar a las herramientas de solo lectura scan, recommend, explain y check. Sirve sobre stdio por defecto; --http ejecuta un servidor remoto que escanea un repositorio público por URL (scan, recommend y explain).

scan --json, recommend --json y check --format json emiten JSON estable y con versión para scripting. Los códigos de salida son el contrato: 0 en éxito, 1 en error (para check: nuevas violaciones con --fail-on new), 2 para un check que no pudo ejecutarse debido a la configuración de CI.

Ejemplo en un repositorio real

Un escaneo real de inbox-zero (apps/web en el commit 11281be, 2,232 archivos TypeScript), recortado a las primeras reglas de cada sección:

Scanned 2,232 TypeScript files
Workspace aliases: 18 resolved

GENERATED RULES
  AP-002  no-ui-layer-in-server-entry      confidence 97%
          A request handler must not import UI components.
          Evidence: 216 of 217 files it applies to follow it (99.5%)
          Exceptions: 1

LAYER BOUNDARIES (review before enforcing)
  utils !-> app  layer boundary   confidence 99%
          Evidence: 650/653 utils files conform (99.5%); 451 app file(s) depend on utils
          Exceptions: 3
  utils !-> components  layer boundary   confidence 99%
          Evidence: 650/653 utils files conform (99.5%); 160 components file(s) depend on utils
          Exceptions: 3
  hooks !-> app  layer boundary   confidence 94%
          Evidence: 65/65 hooks files conform (100%); 121 app file(s) depend on hooks

AP-002 es una familia mecánica, por lo que se auto-genera como aplicación. Los límites de capa se infieren, por lo que se muestran para revisión, no se escriben como aplicación a menos que pases --include-structural. Cada número se mide desde el grafo de importación, no se estima.

Notas técnicas

Modos rápido y profundo. scan por defecto usa un pase rápido a nivel de especificador (sin comprobador de tipos). generate por defecto usa un pase profundo que resuelve a través de barrels y alias de espacio de trabajo, ya que la generación es el punto de compromiso. El análisis estructural (ciclos, huérfanos, alcanzabilidad, API pública) siempre usa el grafo rápido: es fiel a la resolución profunda para esos casos, y la detección de API pública de hecho lo requiere (la resolución profunda resolvería a través de un barrel y borraría la señal barrel-versus-profundo).

Determinismo. El mismo repositorio en la misma versión produce la misma salida. El análisis es puro y ordenado; no hay aleatoriedad, y el motor de análisis está fijado a una versión exacta.

Estado

Publicado en npm y seguro de ejecutar en tu repositorio real. Cada regla está condicionada a revisión por defecto, es reversible en un comando (archprint eject) y determinista, y las reglas generadas son verdes por construcción en el código del que se infirieron.

• Validado a escala: el último censo (archprint 0.12.2, octubre de 2026) ejecutó scan sobre 92,861 repositorios públicos de TypeScript sin fallos; 494 (0.5%) no pudieron obtenerse o agotaron el tiempo, la mayoría eliminados o muy grandes. El flujo de trabajo completo (init, check, allow, generate, check, wire, eject) se ejecutó en una muestra estratificada de 2,019 repositorios: encontró un error, excepciones en carpetas de rutas como Next.js [id], corregido en 0.12.3, y los 2,012 repositorios en los que se ejecutó volvieron exactamente como estaban después de eject.
• Listo para producción hoy: scan y recommend, check para solicitudes de extracción, y auto-aplicación de las familias mecánicas, con una comprobación de autoconsistencia en el momento de generación, un scaffolder init para repositorios nuevos, y cobertura de frameworks en React, Angular, Vue y Svelte. El motor (veinte detectores, la compuerta de confianza y emisores para un archivo ESLint autocontenido, dependency-cruiser, ts-arch y el grafo de capas) está en su lugar y probado.
• Aún por delante: endurecer las familias estructurales hacia la auto-aplicación (una medida real de confianza de rol por archivo, cohesión de capas, ordenamiento del clasificador de roles).
• La versión sigue siendo 0.x, por lo que la superficie de CLI y el formato de reglas pueden refinarse entre versiones menores. Esa es una superficie en maduración, no análisis experimental. El diseño compacto .archprint/ llegó en 0.6.0, y archprint migrate actualiza una configuración más antigua en su lugar.

Un benchmark complementario, AgentRuleBench, mide la cuestión de guía-versus-aplicación directamente (un resultado nulo honesto y pre-registrado en el límite que probó).

Palabras usadas aquí

• Importación: una línea en un archivo que usa código de otro. Las reglas de Archprint tratan sobre qué archivos pueden importar qué.
• Regla de lint / linter: una comprobación automática que se ejecuta en tu código (ESLint es la más común) y marca problemas mientras escribes.
• AUTO / SUGGEST / REJECT: cuán confiado está Archprint en una regla; ver Cómo decide qué confiar.
• Familias mecánicas / estructurales: reglas basadas en señales inequívocas (confiadas sin revisión) versus reglas que dependen de adivinar el rol de una carpeta (retenidas para tu revisión).
• MCP: un estándar abierto que permite a los agentes de IA usar herramientas externas como Archprint.

Documentación

La documentación completa está en tommkruix.github.io/archprint y en docs/: cómo empezar, conceptos (la compuerta de confianza, mecánico vs. estructural, rápido vs. profundo, el ciclo de vida generar/conectar/expulsar), y la referencia de familias de reglas (qué detecta cada regla, cómo se distribuye y cuándo no usarla).

Contribución

Consulta CONTRIBUTING.md. El proyecto se somete a linting, verificación de tipos y pruebas automáticamente; cada cambio mantiene la cobertura por encima de sus umbrales e incluye un changeset.

Licencia

MIT